Menu
▾
▴
docutils-users — General discussions, questions, help requests.
You can subscribe to this list here.
| 2002 |
Jan
|
Feb
|
Mar
|
Apr
|
May
|
Jun
|
Jul
|
Aug
(3) |
Sep
(15) |
Oct
(21) |
Nov
(18) |
Dec
(59) |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 2003 |
Jan
(43) |
Feb
(35) |
Mar
(78) |
Apr
(65) |
May
(163) |
Jun
(169) |
Jul
(137) |
Aug
(77) |
Sep
(47) |
Oct
(27) |
Nov
(43) |
Dec
(68) |
| 2004 |
Jan
(61) |
Feb
(39) |
Mar
(11) |
Apr
(42) |
May
(86) |
Jun
(82) |
Jul
(24) |
Aug
(26) |
Sep
(37) |
Oct
(62) |
Nov
(131) |
Dec
(43) |
| 2005 |
Jan
(31) |
Feb
(56) |
Mar
(65) |
Apr
(165) |
May
(106) |
Jun
(97) |
Jul
(65) |
Aug
(150) |
Sep
(78) |
Oct
(115) |
Nov
(41) |
Dec
(26) |
| 2006 |
Jan
(50) |
Feb
(39) |
Mar
(56) |
Apr
(67) |
May
(89) |
Jun
(68) |
Jul
(116) |
Aug
(65) |
Sep
(58) |
Oct
(103) |
Nov
(28) |
Dec
(52) |
| 2007 |
Jan
(92) |
Feb
(60) |
Mar
(124) |
Apr
(96) |
May
(69) |
Jun
(79) |
Jul
(25) |
Aug
(22) |
Sep
(7) |
Oct
(17) |
Nov
(27) |
Dec
(32) |
| 2008 |
Jan
(57) |
Feb
(87) |
Mar
(51) |
Apr
(43) |
May
(56) |
Jun
(62) |
Jul
(25) |
Aug
(82) |
Sep
(58) |
Oct
(42) |
Nov
(38) |
Dec
(86) |
| 2009 |
Jan
(50) |
Feb
(33) |
Mar
(84) |
Apr
(90) |
May
(109) |
Jun
(37) |
Jul
(22) |
Aug
(51) |
Sep
(93) |
Oct
(86) |
Nov
(31) |
Dec
(62) |
| 2010 |
Jan
(33) |
Feb
(57) |
Mar
(62) |
Apr
(43) |
May
(30) |
Jun
(49) |
Jul
(20) |
Aug
(40) |
Sep
(152) |
Oct
(38) |
Nov
(15) |
Dec
(32) |
| 2011 |
Jan
(29) |
Feb
(25) |
Mar
(65) |
Apr
(45) |
May
(27) |
Jun
(11) |
Jul
(14) |
Aug
(8) |
Sep
(13) |
Oct
(117) |
Nov
(60) |
Dec
(19) |
| 2012 |
Jan
(23) |
Feb
(32) |
Mar
(24) |
Apr
(41) |
May
(56) |
Jun
(24) |
Jul
(15) |
Aug
(11) |
Sep
(26) |
Oct
(21) |
Nov
(12) |
Dec
(31) |
| 2013 |
Jan
(32) |
Feb
(24) |
Mar
(39) |
Apr
(44) |
May
(44) |
Jun
(8) |
Jul
(9) |
Aug
(12) |
Sep
(34) |
Oct
(19) |
Nov
(5) |
Dec
(9) |
| 2014 |
Jan
(22) |
Feb
(12) |
Mar
(7) |
Apr
(2) |
May
(13) |
Jun
(17) |
Jul
(8) |
Aug
(10) |
Sep
(7) |
Oct
(4) |
Nov
|
Dec
(39) |
| 2015 |
Jan
(13) |
Feb
(12) |
Mar
(12) |
Apr
(40) |
May
(5) |
Jun
(22) |
Jul
(3) |
Aug
(42) |
Sep
(5) |
Oct
(10) |
Nov
|
Dec
(10) |
| 2016 |
Jan
(9) |
Feb
(43) |
Mar
(5) |
Apr
(14) |
May
(17) |
Jun
(5) |
Jul
(5) |
Aug
(22) |
Sep
(5) |
Oct
|
Nov
(4) |
Dec
(18) |
| 2017 |
Jan
(28) |
Feb
(29) |
Mar
(9) |
Apr
(23) |
May
(48) |
Jun
(5) |
Jul
(32) |
Aug
(9) |
Sep
(13) |
Oct
(13) |
Nov
(6) |
Dec
(4) |
| 2018 |
Jan
(6) |
Feb
(5) |
Mar
(1) |
Apr
(2) |
May
(5) |
Jun
(17) |
Jul
(12) |
Aug
(15) |
Sep
|
Oct
(2) |
Nov
|
Dec
|
| 2019 |
Jan
|
Feb
(6) |
Mar
(3) |
Apr
(5) |
May
(10) |
Jun
(6) |
Jul
(6) |
Aug
|
Sep
(11) |
Oct
(18) |
Nov
(10) |
Dec
(7) |
| 2020 |
Jan
(3) |
Feb
(14) |
Mar
(2) |
Apr
(1) |
May
(5) |
Jun
|
Jul
(1) |
Aug
(11) |
Sep
(8) |
Oct
|
Nov
(1) |
Dec
(14) |
| 2021 |
Jan
(7) |
Feb
(2) |
Mar
(1) |
Apr
(8) |
May
(23) |
Jun
(7) |
Jul
(10) |
Aug
(1) |
Sep
|
Oct
(7) |
Nov
(10) |
Dec
(2) |
| 2022 |
Jan
|
Feb
(21) |
Mar
|
Apr
(3) |
May
(7) |
Jun
(4) |
Jul
(1) |
Aug
|
Sep
(3) |
Oct
|
Nov
|
Dec
|
| 2023 |
Jan
(18) |
Feb
|
Mar
(1) |
Apr
|
May
(9) |
Jun
|
Jul
|
Aug
(5) |
Sep
|
Oct
|
Nov
|
Dec
|
| 2024 |
Jan
|
Feb
(2) |
Mar
(3) |
Apr
(5) |
May
|
Jun
|
Jul
|
Aug
|
Sep
|
Oct
(2) |
Nov
|
Dec
(2) |
| 2025 |
Jan
(4) |
Feb
|
Mar
(2) |
Apr
(1) |
May
(3) |
Jun
(6) |
Jul
(22) |
Aug
(5) |
Sep
(7) |
Oct
|
Nov
|
Dec
|
|
From: Guenter M. <mi...@us...> - 2025-07-21 00:08:18
|
On 2025-07-14, Schimon Jehudah via Docutils-users wrote: > Good day. > I am interested to know whether it is possible to output an HTML code, > preferably XHTML formatted, without elements "head" nor "body". Yes, this is easily possible with the "publish_parts()" function. https://docutils.sourceforge.io/docs/api/publisher.html#publish-parts (The "html_body" part is the <body> content.) Both, the "html4css1" writer and the "html5" writer export valid XML. Günter |
|
From: Guenter M. <mi...@us...> - 2025-07-21 00:08:13
|
On 2025-07-18, Schimon Jehudah via Docutils-users wrote: > Good afternoon. > Is there any intention to add more tags, such as audio and video? > I did read the object and video reference. > https://docutils.sourceforge.io/docs/ref/rst/directives.html#footnote-reference-1 > I do know that it is possible to add raw HTML code. > https://docutils.sourceforge.io/docs/ref/rst/directives.html#raw-data-pass-through > I think, that having these settled more explicitly would be best, > especially for Atom/RSS attachments (i.e. enclosures). > Please advise. It seems you are looking at reStructuredText as a kind of "HTML-input-language". However, the underlying document model differs from HTML in both, element set and structure: https://docutils.sourceforge.io/docs/ref/doctree.html. While reStructuredText documents can be converted to HTML, this is not the only output format. There is no plan to provide input methods for every HTML element/tag in "stock rST". Especially not for elements that do not have an analogon in other supported output formats like LaTeX/PDF, ODT, or man pages (roff). OTOH, there is this syntax construct called "directive" (https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#directives) whith a set of widely supported standard directives (https://docutils.sourceforge.io/docs/ref/rst/directives.html). These include a directive to include images into the output document, as images are widely used to aide in documentation and supported by most output formats (with limitations). For HTML, this includes moving images. Directives are an extension mechanism, so applications can add their own directives (see, e.g. Sphinx for a large set of additional directives). The downside is, that documents using custom directives cannot be handled by the "vanilla" Docutils tools. Günter |
|
From: Schimon J. <sc...@fe...> - 2025-07-19 18:33:53
|
Good evening. Never mind. Please ignore my message. I am attempting to create an Atom Syndication Format based content management system (i.e. static site generator), and I have mixed RST with XML. Also, I can add attribute "class" to elements which I want to be of enclosure or anything else. This is a concern of software-level. Regards, Schimon On Sat, 19 Jul 2025 16:40:53 +0200 Marc Rintsch <ma...@ri...> wrote: > On 18.07.25 15:57, Schimon Jehudah via Docutils-users wrote: > > Should reStructuredText have a directive for enclosures? > > > > It is possible to scan HTML code for potential attachments (e.g. > > torrent, ipfs, magnet, ogg, etc.), yet it might be better to have an > > explicit directive to indicate of a media which is intended to be > > realized as an attachment. > > I'm a bit puzzled what is meant by the terms „enclosure“ and > „attachment“ here. That's not really terminology used in > reStructuredText or HTML. > > Ciao, > Marc 'BlackJack' Rintsch |
|
From: Marc R. <ma...@ri...> - 2025-07-19 15:14:07
|
On 18.07.25 15:57, Schimon Jehudah via Docutils-users wrote:
> Should reStructuredText have a directive for enclosures?
>
> It is possible to scan HTML code for potential attachments (e.g.
> torrent, ipfs, magnet, ogg, etc.), yet it might be better to have an
> explicit directive to indicate of a media which is intended to be
> realized as an attachment.
I'm a bit puzzled what is meant by the terms „enclosure“ and
„attachment“ here. That's not really terminology used in
reStructuredText or HTML.
Ciao,
Marc 'BlackJack' Rintsch
--
Norton SystemWorks 2002 includes a file erasure program called
Wipe Info. In the manual (page 160), we learn that “Wipe Info uses
hexadecimal values to wipe files. This provides more security than
wiping with decimal values.” Who writes this stuff?
-- Bruce Schneier in CRYPTO-GRAM
|
|
From: Schimon J. <sc...@fe...> - 2025-07-18 15:59:03
|
Good afternoon. Should reStructuredText have a directive for enclosures? It is possible to scan HTML code for potential attachments (e.g. torrent, ipfs, magnet, ogg, etc.), yet it might be better to have an explicit directive to indicate of a media which is intended to be realized as an attachment. Perhaps a value for attribute "class" would be more appropriate. Please advise. Kind regards, Schimon |
|
From: Schimon J. <sc...@fe...> - 2025-07-18 15:55:43
|
Good afternoon. Is there any intention to add more tags, such as audio and video? I did read the object and video reference. https://docutils.sourceforge.io/docs/ref/rst/directives.html#footnote-reference-1 I do know that it is possible to add raw HTML code. https://docutils.sourceforge.io/docs/ref/rst/directives.html#raw-data-pass-through I think, that having these settled more explicitly would be best, especially for Atom/RSS attachments (i.e. enclosures). Please advise. Kind regards, Schimon |
|
From: Schimon J. <sc...@fe...> - 2025-07-14 17:55:25
|
Alan. Good evening. Thank you very much! https://git.xmpp-it.net/sch/Rivista/commit/9f422a8813e467db5ae62e850c660d02c0601e45 Respectfully, Schimon On Mon, 14 Jul 2025 09:28:14 -0400 Alan <ala...@gm...> wrote: > Here is what (free) Copilot says. > > [image: image.png] > > On Mon, Jul 14, 2025 at 8:30 AM Schimon Jehudah via Docutils-users < > doc...@li...> wrote: > > > Good day. > > > > I am interested to know whether it is possible to output an HTML > > code, preferably XHTML formatted, without elements "head" nor > > "body". > > > > I am working with Atom Syndication Format and XSLT, and therefore, > > I am not interested in creating elements "head" or "body", because > > XSL Transformations already does the XHTML task. > > > > Kind regards, > > Schimon > > > > |
|
From: Alan <ala...@gm...> - 2025-07-14 13:28:51
|
Here is what (free) Copilot says. [image: image.png] On Mon, Jul 14, 2025 at 8:30 AM Schimon Jehudah via Docutils-users < doc...@li...> wrote: > Good day. > > I am interested to know whether it is possible to output an HTML code, > preferably XHTML formatted, without elements "head" nor "body". > > I am working with Atom Syndication Format and XSLT, and therefore, I am > not interested in creating elements "head" or "body", because XSL > Transformations already does the XHTML task. > > Kind regards, > Schimon > > > _______________________________________________ > Docutils-users mailing list > Doc...@li... > https://lists.sourceforge.net/lists/listinfo/docutils-users > > Please use "Reply All" to reply to the list. > |
|
From: Schimon J. <sc...@fe...> - 2025-07-14 12:29:03
|
Good day. I am interested to know whether it is possible to output an HTML code, preferably XHTML formatted, without elements "head" nor "body". I am working with Atom Syndication Format and XSLT, and therefore, I am not interested in creating elements "head" or "body", because XSL Transformations already does the XHTML task. Kind regards, Schimon |
|
From: Viktor R. <vik...@gm...> - 2025-06-30 12:12:26
|
Hello Docutils Community, Am Mo., 30. Juni 2025 um 13:44 Uhr schrieb Viktor Ransmayr < vik...@gm...>: > Hello Docutils Community, > > I use 'docutils' to organize my notes as HTML files - and - store links > for later review. > > I noted issues with certain IETF mailarchive URIs already a while ago - > but - only now took the time to follow up & create a simple test file (see > attachment) demonstrating the issue. > > This file contains two IETF mailarchive URI instances. - The first one is > processed without an issue - and - the second one is processed with an > error. - That is, when I create the HTML file I receive the following > 'Docutils System Message': > > ### > > [user@fedora-python-study-vm vransmayr]$ > [user@fedora-python-study-vm vransmayr]$ docutils test-IETF-URI-issue.rst > test-IETF-URI-issue.html > test-IETF-URI-issue.rst:18: (ERROR/3) Unknown target name: "k4-l4mk7qa". > [user@fedora-python-study-vm vransmayr]$ > > ### > > For me it is not clear, if the second mailarchive URI really does > 'violate' the reStructuredText Markup Specification - or - if it is a > 'docutils' issue. > > Looking forward to your feedback ! > > With kind regards, > > Viktor > > PS: This issue occurs in docutils version 0.21.2 as well as 0.22rc5 ... > For easier access: Here's the created HTML file as well. With kind regards, Viktor |
|
From: Viktor R. <vik...@gm...> - 2025-06-30 11:44:35
|
Hello Docutils Community, I use 'docutils' to organize my notes as HTML files - and - store links for later review. I noted issues with certain IETF mailarchive URIs already a while ago - but - only now took the time to follow up & create a simple test file (see attachment) demonstrating the issue. This file contains two IETF mailarchive URI instances. - The first one is processed without an issue - and - the second one is processed with an error. - That is, when I create the HTML file I receive the following 'Docutils System Message': ### [user@fedora-python-study-vm vransmayr]$ [user@fedora-python-study-vm vransmayr]$ docutils test-IETF-URI-issue.rst test-IETF-URI-issue.html test-IETF-URI-issue.rst:18: (ERROR/3) Unknown target name: "k4-l4mk7qa". [user@fedora-python-study-vm vransmayr]$ ### For me it is not clear, if the second mailarchive URI really does 'violate' the reStructuredText Markup Specification - or - if it is a 'docutils' issue. Looking forward to your feedback ! With kind regards, Viktor PS: This issue occurs in docutils version 0.21.2 as well as 0.22rc5 ... |
|
From: engelbert g. <eng...@gm...> - 2025-06-24 07:13:07
|
Hei everyone, only one change: Don't report an error for duplicate targets with identical refname all the best e |
|
From: engelbert g. <eng...@gm...> - 2025-06-17 13:15:36
|
Hei everyone, today june 17th rc4 is out. the final 0.22 is scheduled for end of july, start of august. cheers e |
|
From: engelbert g. <eng...@gm...> - 2025-06-17 10:56:31
|
Hei everyone, next pre-release, This release often works in clarifying things, thanks to all the testers and many thanks to Günter for the work. Changes that should be run through pre-release * Drop the "name" option of the "target-notes" directive. (Report an error instead of silently ignoring the value.) * New alias "rst-class" for the "class" directive to improve the compatibility with Sphinx. * "Downgrade" targets generated from hyperlink references with embedded URI or alias from explicit to implicit (i.e. similar to the targets for sections, see implicit hyperlink targets for details). thanks for your patience and help e |
|
From: engelbert g. <eng...@gm...> - 2025-06-10 20:36:37
|
Hei minimal changes and fixes manpage writer no longer drops the text of internal targets 0.22 in one week ... if ... :-) cheers and thanks to günter e |
|
From: engelbert g. <eng...@gm...> - 2025-05-22 19:46:37
|
Hei everyone,
only a few changes, but necessary ones to remedy 3rd party problems
please try, test
next release day for 0.22 on my schedule is tuesday june 10.
all the best
e
* docutils/parsers/rst/directives/misc.py
- Pass default settings to custom parser for included file.
* docutils/parsers/rst/states.py
- Remove the list`states.RSTStateMachine.memo.section_parents`
(introduced in Docutils 0.22rc1) that broke 3rd-party applications
setting up a "mock memo".
- Use `types.SimpleNamespace` instead of a local definition for
the auxilliary class `states.Struct`.
* docutils/writers/_html_base.py
- Fix error when determining the document metadata title from the
source path and the internal `source` attribute is None.
|
|
From: engelbert g. <eng...@gm...> - 2025-05-20 12:56:09
|
Hei everyone, the plan changed 0.22rc2 is for thursday may, 22 0.22 if nothing crops up tuesday june, 10th all the best e |
|
From: engelbert g. <eng...@gm...> - 2025-05-06 17:29:55
|
hei everyone please try and test. Many changes for details see https://docutils.sourceforge.io/HISTORY.html reStructuredText: - Support `CSS3 units`_. This adds "ch", "rem", "vw", "vh", "vmin", "vmax", and "Q" to the `supported length units`__. Note that some output formats don't support all units. - New option "figname" for the `"figure"`_ directive. .. _CSS3 units: https://www.w3.org/TR/css-values-3/#lengths __ docs/ref/rst/restructuredtext.html#length-units Document Tree / Docutils DTD - Allow multiple <term> elements in a `\<definition_list_item>`__ (third-party writers may need adaption). - The first element in a <figure> may also be a <reference> (with nested "clickable" <image>). __ docs/ref/doctree.html#definition-list-item Configuration changes - Make MathML the default math_output_ for the "html5" writer. - Change the default input_encoding_ from ``None`` (auto-detect) to "utf-8". - Drop short options ``-i`` and ``-o``. Use the long equivalents ``--input-encoding`` and ``--output-encoding``. (See `command line interface`_ for the rationale.) - Rename configuration setting "output" to "output_path_". - The manpage writer now recognizes the sections [writers] and [manpage writer] with the new setting `text_references`_. Output changes LaTeX: Don't wrap references with custom reference-label_ in a ``\hyperref`` command. The "hyperref" package generates hyperlinks for labels by default, so there is no change in the PDF (except for "ref*"). Stop requiring "ifthen.sty". Replace use of ``\ifthenelse{\isundefined...`` with the eTeX primitive ``\ifdefined``. HTML5: Unitless image_ size measures__ are written as <img> "width" and "hight" values instead of "style" rules. The current behaviour is kept for values with units, so users may specify, e.g. ``:width: 50px`` instead of ``:width: 50`` to override CSS stylesheet rules. __ docs/ref/doctree.html#measure manpage: Don't UPPERCASE section headings. Handle hyperlink references (see text_references_). null: The "null" writer output changed from None to the empty string. `publish_string()` now returns a `bytes` or `str` instance for all writers (as documented). New objects `parsers.docutils_xml` parser for `Docutils XML`_ (e.g., the output of the "xml" writer). Provisional. Try ``docutils --parser=xml test/data/multiple-term-definitions.xml`` or use the :parser: option of the `"include"`_ directive to include an XML file in a rST document. `nodes.Element.validate()` Raise `nodes.ValidationError` if the element does not comply with the `Docutils Document Model`_. Provisional. `writers.DoctreeTranslator` Generic Docutils document tree translator base class with `uri2path()` auxiliary method. Provisional. Removed objects `core.Publisher.setup_option_parser()` internal, obsolete, `frontend.ConfigParser.get_section()` obsoleted by the configparser's "Mapping Protocol Access", `frontend.OptionParser.set_defaults_from_dict()` obsolete, `nodes.Element.set_class()` obsolete, append to Element['classes'] directly, `parsers.rst.directives.tables.CSVTable.decode_from_csv()` not required with Python 3, `parsers.rst.directives.tables.CSVTable.encode_from_csv()` not required with Python 3, `transforms.writer_aux.Compound` not used since Dec 2010, `utils.error_reporting` obsolete in Python 3, `utils.Reporter.set_conditions()` obsolete, set attributes via configuration settings or directly. Removed localisations Mistranslations of the "admonition" directive name: Use "advies" (af), "varsel" (da), "warnhinweis" (de), "aviso" (es), "sciigo" (eo), "annonce" (fr), "avviso" (it), "advies" (nl), "zauważenie" (pl) (introduced in Docutils 0.21) or the English name "admonition". New files ``docutils/parsers/rst/include/html-roles.txt`` `Standard definition file`_ for additional roles matching HTML tags. Removed files ``tools/rst2odt_prepstyles.py`` Obsoleted by `writers.odf_odt.prepstyles`. ``docutils/utils/roman.py`` Obsoleted by ``docutils/utils/_roman_numerals.py`` Bugfixes and improvements (see HISTORY_). |
|
From: engelbert g. <eng...@gm...> - 2025-04-30 00:40:21
|
hello everyone,
the plan
* freeze now, only small corrections to the code till release
* 0.22rc1 on tuesday may 6th
* 0.22 on tuesday may 21th if no stopper shows up.
after more than a year a lot of changes have accumulated, some
* General
- We have started to add type hints to Docutils (feature-request #87).
This will be a complex programme of work and as such,
for the time being, these type hints are "provisional"
and should not be relied upon.
By default, the Python interpreter treats type hints as annotations.
Python >= 3.10 is required with active type hints
(``typing.TYPE_CHECKING == True``).
* docutils/frontend.py
- Drop short options ``-i`` and ``-o`` for ``--input-encoding``
and ``--output-encoding``.
* very many internal changes, to clarify and stabilize
* docutils/writers/_html_base.py
- Make MathML the default math_output_.
- ...
* docutils/writers/latex2e
- Support SVG image inclusion with the "svg" LaTeX package (see the
- and more
* docutils/writers/manpage.py
- better reference (URI) support
in detail https://docutils.sourceforge.io/HISTORY.html
all the best
e
|
|
From: Guenter M. <mi...@us...> - 2025-03-26 13:31:56
|
Dear Arne, On 2025-03-25, Arne Skjærholt wrote: ... > The use case I'm working with is making a solution for non-technical > users to edit templates [...] ... > Consider, the following fragment (obviously simplified, but it should > communicate how I intend it to work): > .. loop-construct: > This text is repeated, but with a varying value: :getfield:`fieldname`. ... > What happens is that when a section is encountered that is a sibling > of the current section level or higher in the section tree, the > parsing state gets scrolled back to just before the offending section > header, and EOFError is raised.[0] This error percolates up the stack, > unwinding the section state as we go, until we get to a state where we > can continue. The Docutils document model allows section__ elements only inside the main document or other sections. __ https://docutils.sourceforge.io/docs/ref/doctree.html#section There is no official support for section markup in nested content. Did you nest section title syntax inside the directive content? > The practical result of this is that the contents of my directive get > truncated just before the section header each time around the loop, > which is obviously not ideal. I've tried a couple of different > approaches to getting this right, but nothing that quite works. The > closest I've gotten involves looking at the return value from the > nested parse, and when there's material left over taking the remaining > lines, injecting the directive in front of those lines and indenting > them before reinserting them into the input stream with > self.state_machine.insert_input(). That sort of work, but I'm pretty > sure it won't propagate the loop state correctly outside of the tiny > example I've been using to debug this issue. > Does anyone have suggestions on how to best handle this? I'm open to > alternate ways of implementing the looping logic, but it really does > need to loop I'm afraid and I think all my alternate ideas have so far > run into some issue with threading the state correctly while still > also getting everything into the output. A typical approach would be to make the "loop-construct" directive insert a <pending> element that stores the data during the parsing step while a matching transform__ does the actual looping. See "class", "target-notes", "sectnum" and "contents" directives for examples. However, even then, starting sister-sections or parent-sections inside the directive content would not be possible. Could you give a more detailled example how you plan to specify the "underlying list" and the text to loop over? |
|
From: Arne S. <arn...@gm...> - 2025-03-25 18:05:00
|
Dear all, I am working on an application of docutils/rST, but I'm running into a snag with how sections find their place in the tree using exceptions for control flow. The use case I'm working with is making a solution for non-technical users to edit templates that will be used to produce the final documents. So basically a templating solution, but domain-specific and couched in the terms of the domain rather than explicit logic. This is probably somewhat counter to how rST is intended to be used, but I still think it could be a good solution. Mostly things are working out quite well, but the way sections are implemented in the rST parsing of docutils interacts poorly with my construct that has a looping logic. Consider, the following fragment (obviously simplified, but it should communicate how I intend it to work): .. loop-construct: This text is repeated, but with a varying value: :getfield:`fieldname`. The way it's implemented is that the loop-construct directive loops over the underlying list, setting the value in a contextvars.ContextVar and calling self.state.nested_parse on the content each time, producing the elements that get inserted into the output. This works quite well, until section headers get involved. What happens is that when a section is encountered that is a sibling of the current section level or higher in the section tree, the parsing state gets scrolled back to just before the offending section header, and EOFError is raised.[0] This error percolates up the stack, unwinding the section state as we go, until we get to a state where we can continue. 0: docutils.parsers.rst.states.py, line 361 in RSTState.check_subsection in my copy of docutils-0.21.2 The practical result of this is that the contents of my directive get truncated just before the section header each time around the loop, which is obviously not ideal. I've tried a couple of different approaches to getting this right, but nothing that quite works. The closest I've gotten involves looking at the return value from the nested parse, and when there's material left over taking the remaining lines, injecting the directive in front of those lines and indenting them before reinserting them into the input stream with self.state_machine.insert_input(). That sort of work, but I'm pretty sure it won't propagate the loop state correctly outside of the tiny example I've been using to debug this issue. Does anyone have suggestions on how to best handle this? I'm open to alternate ways of implementing the looping logic, but it really does need to loop I'm afraid and I think all my alternate ideas have so far run into some issue with threading the state correctly while still also getting everything into the output. Arne :wq |
|
From: Kayce B. <ka...@go...> - 2025-01-08 19:28:54
|
Hi Guenter, thanks for the information. Using the starting line of the next sibling (or child) node sounds like a promising and elegant solution! I usually walk the node tree section-by-section so that feels like it may work very well. I'll try it out and follow up here with results. On Mon, Jan 6, 2025 at 3:01 AM Guenter Milde via Docutils-users < doc...@li...> wrote: > On 2025-01-02, Kayce Basques via Docutils-users wrote: > ... > > Hello! I believe this is my first message in the Docutils community. I'm > a > > big fan of Sphinx and appreciate the core role that Docutils plays in > > Sphinx. I subscribed to this list and am excited to be more active in the > > community. > > Hello and welcome to the list. > > > I'm working on a Sphinx extension. In my doctree-resolved handler I > > recursively walk through all section nodes. When the extension detects > > something that can be improved in the underlying content, it's often > > possible for the extension to make the edits automatically. Is the line > > property of the Node class the only reference back to the underlying > > reStructuredText? > > The internal attributes ``node.source`` and ``node.line`` hold the path > or description of the input source and its start-line number respectively > (cf. docutils.nodes.Node.source and docutils.nodes.Node.line). > > * ``node.source`` differs from the global document source for parts > included by the "include" directive. > * Not every node has these attributes > (cf. https://sourceforge.net/p/docutils/feature-requests/41/). > For inline nodes, the attributes of the parent block-level node are used > in error reporting. > > Additionally, there is the internal `rawsource` attribute that is set in > docutils.nodes.Element.__init__`. It comes with a caveat:: > > """The raw text from which this element was constructed. > > For informative and debugging purposes. Don't rely on its value! > > NOTE: some elements do not set this value (default ''). > """ > > > Just wanted to check that there's no explicit reference > > to the end line of the node, and I'm expected to manually compute the end > > line. The manual computation has been kinda error-prone and brittle for > me > > so far. Seems like the implementation could be much simpler and > bulletproof > > if reST explicitly gave me the end line. Just wanted to make sure there's > > no better way to do this. > > For block-level elements, you may consider using the start line of the > next node as a starting point. > > > One example of the manual computation I'm alluding to: > > > from docutils.nodes import section > > > def do_stuff(app, doc_tree, doc_name): > > for node in doc_tree.traverse(section): > > text = node.astext() > > start = node.line > > end = start + len(text.splitlines()) # Often incorrect > > … > > # A better approach might be to get the first and last lines > > # of text and search for those delimiters in the source > > Two suggestions (untested):: > > - text = node.astext() > + text = node.rawsource or node.astext() > > or :: > > - end = start + len(text.splitlines()) # Often incorrect > + end = node.next_node(descend=False, siblings=True, > + ascend=True).line - 1 > > > I hope this may get you started on experimenting... > > > A happy new year to all Docutils users and developers, > > Günter > > > > _______________________________________________ > Docutils-users mailing list > Doc...@li... > https://lists.sourceforge.net/lists/listinfo/docutils-users > > Please use "Reply All" to reply to the list. > |
|
From: Guenter M. <mi...@us...> - 2025-01-06 11:00:59
|
On 2025-01-02, Kayce Basques via Docutils-users wrote: ... > Hello! I believe this is my first message in the Docutils community. I'm a > big fan of Sphinx and appreciate the core role that Docutils plays in > Sphinx. I subscribed to this list and am excited to be more active in the > community. Hello and welcome to the list. > I'm working on a Sphinx extension. In my doctree-resolved handler I > recursively walk through all section nodes. When the extension detects > something that can be improved in the underlying content, it's often > possible for the extension to make the edits automatically. Is the line > property of the Node class the only reference back to the underlying > reStructuredText? The internal attributes ``node.source`` and ``node.line`` hold the path or description of the input source and its start-line number respectively (cf. docutils.nodes.Node.source and docutils.nodes.Node.line). * ``node.source`` differs from the global document source for parts included by the "include" directive. * Not every node has these attributes (cf. https://sourceforge.net/p/docutils/feature-requests/41/). For inline nodes, the attributes of the parent block-level node are used in error reporting. Additionally, there is the internal `rawsource` attribute that is set in docutils.nodes.Element.__init__`. It comes with a caveat:: """The raw text from which this element was constructed. For informative and debugging purposes. Don't rely on its value! NOTE: some elements do not set this value (default ''). """ > Just wanted to check that there's no explicit reference > to the end line of the node, and I'm expected to manually compute the end > line. The manual computation has been kinda error-prone and brittle for me > so far. Seems like the implementation could be much simpler and bulletproof > if reST explicitly gave me the end line. Just wanted to make sure there's > no better way to do this. For block-level elements, you may consider using the start line of the next node as a starting point. > One example of the manual computation I'm alluding to: > from docutils.nodes import section > def do_stuff(app, doc_tree, doc_name): > for node in doc_tree.traverse(section): > text = node.astext() > start = node.line > end = start + len(text.splitlines()) # Often incorrect > … > # A better approach might be to get the first and last lines > # of text and search for those delimiters in the source Two suggestions (untested):: - text = node.astext() + text = node.rawsource or node.astext() or :: - end = start + len(text.splitlines()) # Often incorrect + end = node.next_node(descend=False, siblings=True, + ascend=True).line - 1 I hope this may get you started on experimenting... A happy new year to all Docutils users and developers, Günter |
|
From: Kayce B. <ka...@go...> - 2025-01-04 17:52:16
|
Adam Turner sent me this response on the Write The Docs Slack: "Docutils isn’t a format preserving parser — there have been various experimental rST writers but nothing official yet. Your best bet is likely using the source line information and reading from the source file yourself." https://writethedocs.slack.com/archives/C0899Q0G1/p1735852921645109 On Thu, Jan 2, 2025 at 2:58 PM Kayce Basques <ka...@go...> wrote: > Hello! I believe this is my first message in the Docutils community. I'm a > big fan of Sphinx and appreciate the core role that Docutils plays in > Sphinx. I subscribed to this list and am excited to be more active in the > community. > > I'm working on a Sphinx extension. In my doctree-resolved handler I > recursively walk through all section nodes. When the extension detects > something that can be improved in the underlying content, it's often > possible for the extension to make the edits automatically. Is the line > property of the Node class the only reference back to the underlying > reStructuredText? Just wanted to check that there's no explicit reference > to the end line of the node, and I'm expected to manually compute the end > line. The manual computation has been kinda error-prone and brittle for me > so far. Seems like the implementation could be much simpler and bulletproof > if reST explicitly gave me the end line. Just wanted to make sure there's > no better way to do this. > > One example of the manual computation I'm alluding to: > > > from docutils.nodes import section > > def do_stuff(app, doc_tree, doc_name): > for node in doc_tree.traverse(section): > text = node.astext() > start = node.line > end = start + len(text.splitlines()) # Often incorrect > … > # A better approach might be to get the first and last lines > # of text and search for those delimiters in the source > > def setup(app): > app.connect('doctree-resolved', do_stuff) > return { > 'version': '0.0.0', > 'parallel_read_safe': True, > 'parallel_write_safe': True, > } > |
|
From: Kayce B. <ka...@go...> - 2025-01-02 23:06:53
|
Hello! I believe this is my first message in the Docutils community. I'm a
big fan of Sphinx and appreciate the core role that Docutils plays in
Sphinx. I subscribed to this list and am excited to be more active in the
community.
I'm working on a Sphinx extension. In my doctree-resolved handler I
recursively walk through all section nodes. When the extension detects
something that can be improved in the underlying content, it's often
possible for the extension to make the edits automatically. Is the line
property of the Node class the only reference back to the underlying
reStructuredText? Just wanted to check that there's no explicit reference
to the end line of the node, and I'm expected to manually compute the end
line. The manual computation has been kinda error-prone and brittle for me
so far. Seems like the implementation could be much simpler and bulletproof
if reST explicitly gave me the end line. Just wanted to make sure there's
no better way to do this.
One example of the manual computation I'm alluding to:
from docutils.nodes import section
def do_stuff(app, doc_tree, doc_name):
for node in doc_tree.traverse(section):
text = node.astext()
start = node.line
end = start + len(text.splitlines()) # Often incorrect
…
# A better approach might be to get the first and last lines
# of text and search for those delimiters in the source
def setup(app):
app.connect('doctree-resolved', do_stuff)
return {
'version': '0.0.0',
'parallel_read_safe': True,
'parallel_write_safe': True,
}
|
86 messages has been excluded from this view by a project administrator.
