Activity for Docutils: Documentation Utilities
-
Günter Milde posted a comment on ticket #509
This should be fixed in [r10227]. Could you re-try?
-
qemu build problem after docutils update to 0.22
-
This should be fixed in [r10227]. Could you re-try?
-
Adjustments for nested_parse().
-
rST parser: restore backwards compatibility of nested parsing.
-
Ernstkm modified a comment on ticket #507
No, not a cache problem. The URL is https://www.docutils.org/rst.html. It's a live page that you can't get to except through search engine results (where it ranks highly) or having bookmarked the URL, but that live page has broken links. The broken links I'm referring to specifically are: https://www.docutils.org/docs/user/rst/quickstart.txt https://www.docutils.org/docs/user/rst/cheatsheet.txt These each result in a 404 error page from GitHub. What I'm wondering is, where would I go to help fix...
-
No, not a cache problem. The URL is https://www.docutils.org/rst.html. It's a live page that you can't get to except through search engine results (where it ranks highly) or having bookmarked the URL, but that live page has broken links. The broken links are, specifically: https://www.docutils.org/docs/user/rst/quickstart.txt https://www.docutils.org/docs/user/rst/cheatsheet.txt These result in a 404 error page from GitHub. What I'm wondering is, where would I go to help fix this: Sourceforge or...
-
No, not a cache problem. The URL is https://www.docutils.org/rst.html. It's a live page that you can't get to except through search engine results (where it ranks highly) or having bookmarked the URL, but that live page has broken links. The broken links are, specifically: https://www.docutils.org/docs/user/rst/quickstart.txt https://www.docutils.org/docs/user/rst/cheatsheet.txt These result in a 404 error page from GitHub. What I'm wondering is, where would I go to help fix this: Sourceforge or...
-
No, not a cache problem. The URL is https://www.docutils.org/rst.html. It's a live page that you can't get to except through search engine results (and it ranks highly), but the live page has broken links. The broken links are, specifically: https://www.docutils.org/docs/user/rst/quickstart.txt https://www.docutils.org/docs/user/rst/cheatsheet.txt These result in a 404 error page from GitHub. What I'm wondering is, where would I go to help fix this: Sourceforge or GitHub? One project refers to https://docutils.sourceforge.io...
-
Consider the use cases: a) A main document includes rST blocks from various different sources (other projects documentation, docstrings, ...). We cannot guarantee a consistent title style hierarchy across all inclusions and want to use a separate title style hierarchy in the included blocks. b) A main document includes chapters from other source files of the same project after an introductory section. The project uses consistent title styles in all files. We want a document-wide title style hierarchy,...
-
assuming the included document. is complete, has a consistent title hierarchy means first title-style is top, next is 2nd asf standard use case is to include the document at a position where it's top level is one below the current in the including document e.g. section l1 ========== section l2 ---------- .. included doc section l3 ========== section l4 ---------- .. including doc section l2 ---------- is there a use case for including and setting a different level, absolute or relative ?
-
assuming the included document. is complete, has a consistent title hierarchy means first title-style is top, next is 2nd asf standard use case is to include the document at a position where it's top level is one below the current in the including document e.g. section l1 ========== section l2 .. included doc section l3 ========== section l4 ---------- .. including doc section l2 is there a use case for including and setting a different level, absolute or relative ?
-
Problems with nested parsing and sections.
-
engelbert gruber posted a comment on ticket #511
assuming the included document. is complete, has a consistent title hierarchy means first title-style is top, next is 2nd asf standard use case is to include the document at a position where it's top level is one below the current in the including document e.g. section l1 ========== section l2 .. included doc section l3 ========== section l4 ---------- .. including doc section l2 is there a use case for including and setting a different level, absolute or relative ? On Fri, 29 Aug 2025 at 23:25,...
-
An alternative idea: nested parse uses the document-wide title style hierarchy if the "node" argument is left at its default value. The result of the nested parsing is directly added to the document (at the "current" node). Sections are appended according to their level.
-
Deprecate the "match_titles" argument of `states.RSTState.nested_list_parse()`.
-
More distict variable name in parsers.rst.states.RSTState.nested_list_parse().
-
New attribute to store the parent state machine of nested state machines.
-
An idea how to fix Sphinx's "only" directive with a new internal attribute "title_style" for the nodes.section element.
-
Element after a section from nested parsing may be invalid. parsers.rst.RSTSTate.nested_parse() with match_titles=True (i.e. support for sections) leads to an invalid document tree, if the nested block contains a section but the element following the nested block is not a section. The structure model ony allows a <section> as sibling after a <section>. An invalid doctree can be prevented if the following content is appended to the last nested section instead of its parent. The "nested" directive...
-
Problems with nested parsing and sections.
-
Problems with nested parsing and sections.
-
Problems with nested parsing and sections.
-
Element after a section from nested parsing may be invalid.
-
Release date for 0.22 is in the future
-
Thanks for the report. This is fixed in the repository. A fixup release will take some time, because of [bugs:#508] and [bugs:#509] prove tricky...
-
Use a "property" for `parsers.rst.states.RSTState.parent`.
-
Dilian Wesselinov Palauzov created ticket #510
Release date for 0.22 is in the future
-
Fix/Update tests for nested parsing with sections.
-
LaTeX writer fails to generate "labels" for some elements with "ids".
-
Fixed in [r10219].
-
LaTeX writer: write "label" commands for elements with "ids".
-
LaTeX writer: dont add `\phantomsection` for subtitle labels.
-
LaTeX writer: Simplify code for nested image.
-
LaTeX writer: fix anchor placement for figures, images, literal blocks, tables.
-
LaTeX writer: set anchor for math-block with target/label.
-
Documentation fixes.
-
version string 0.23b.dev
-
set path to docutils dev code
-
Give better messages on malformed tables
-
Fixed in [r10208]. Thank you for report and patch.
-
errors for malformed tables do not indicate what the error is
-
Fixed in [r10208]. Thank you for report and patch.
-
The reason is an incompatibility of Sphinx or one of the Sphinx extensions with the new section parsing algorithm introduced in commit [r10093] with updates in [r10129], [r10131], [r10131]. The unhelpful "TypeError" is displayed because Sphinx carries on after a CRITICAL problem which leads to follow-up problems (here, self.parent beeing None instead of an Element instance). The error reported by Docutils gives some hints. Let's dissect the first message: /scratch/emulators/qemu/work/qemu-10.0.3/docs/../system/qtest.c:70:...
-
Could you re-try with [r10197] or the attached patch if this gets a more telling log and maybe some output?
-
Better error reports for hyperlinks with embedded URI or alias.
-
latex writer: Fix/simplify footnote handling.
-
Use True/False instead of 1/0 for boolean `blank_finish`.
-
Better error reporting for table markup.
-
Simplify the determination of table opening LaTeX code.
-
rST parser: ensure that nested parsing only appends to the provided base node.
-
Test nested parsing in a directive.
-
Good news. The remaining warnings are from a different issue (see the comment by Peter Maydell). I will do some more testing and cleanups. Then we can release a new Docutils version. Thank you for report and testing.
-
Thomas Klausner posted a comment on ticket #508
I applied all changes since the 0.22 release to my copy (except the version bump in init.py) There are no CRITICAL errors, the section of the build looks like this: [6203/6204] Generating docs/QEMU manual with a custom command Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597. Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc...
-
Could you re-try with a checkout or snapshot of [r10204] that introduces independent section title style hierarchies for nested parsing?
-
rST parser: new title-style hierarchy for nested parsing with detached base node.
-
Look for valid parent before appending a section element.
-
Fixes for the section level determination.
-
Deprecate parsers.rst.states.RSTStateMachine.memo.reporter.
-
Peter Maydell posted a comment on ticket #508
Those "possible precedence problem" warnings are from the kernel-doc perl script -- I guess that you're using a new version of Perl which emits the warnings. They shouldn't be relevant to this docutils issue, I think. (We're going to upgrade our kernel-doc script to the kernel's current one, which is a complete rewrite in Python; that will fix these warnings as a side effect.)
-
The precedence errors are there with docutils 0.21 as well: Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597. Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597. Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597. Possible...
-
The precedence errors are there with docutils 0.21 as well: Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597. Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597. Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597. Possible...
-
Looking at docs/sphinx/kerneldoc.py, I see that it uses Docutil's RSTState.nested_parse() which (up to now) forces a consistent title style hierarchy. OTOH, quapidoc uses Sphinx's nested_parse_with_titles() that starts a new title style hierarchy. Could you check, if the remaining CRITICAL errors also show up with Docutils 0.21?
-
I am working on a fix...
-
<REDACTED> posted a comment on ticket #508
The docstrings in this case are not from the qapidoc sphinx extension, but from docs/sphinx/kerneldoc.py (which we have borrowed from the Linux kernel's sphinx documentation).
-
I've now reported this to the qemu project at https://gitlab.com/qemu-project/qemu/-/issues/3077
-
qemu build problem after docutils update to 0.22
-
Did you check the generated HTML for missing section headings? While the build runs without crashing, there are still serious errors. Unfortunately, I cannot replicate or trace the reason. Here is what I found so far: The error is in docstrings that are collected by a Sphinx extension (qapidoc?). The error message tells, that the parser expects a consistent hierarchy of title adornment styles (i.e. sections in docstrings under/overlined with *, subsections underlined with -). Docstrings using this...
-
Chris Crawford posted a comment on ticket #507
Is it cached? --Chris On Tue, Aug 12, 2025, 21:55 Ernstkm ernstkm@users.sourceforge.net wrote: The URL https://www.docutils.org/rst.html still appears high in search engine results for "restructuredtext cheatsheet," and still contains the broken links. That appears to be hosted with GitHub Pages. Is docutils.org officially associated with this (SourceForge) project, and if so, where would I send the patch / PR if I wanted to help out? [bugs:#507] https://sourceforge.net/p/docutils/bugs/507/ renamed...
-
The URL https://www.docutils.org/rst.html still appears high in search engine results for "restructuredtext cheatsheet," and still contains the broken links. That appears to be hosted with GitHub Pages. Is docutils.org officially associated with this (SourceForge) project, and if so, where would I send the patch / PR if I wanted to help out?
-
In this case, the problem seems to be an incompatibility with Sphinx contrib extension "autoprogram". Can you please try with an updated repository version of Docutils? Commit [r10200] should fix it.
-
I added the second patch (r10200) as well, and qemu still builds fine. The warnings are now: [6203/6204] Generating docs/QEMU manual with a custom command 23:12:53 [659/1913] Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597. Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597. Possible precedence problem between !...
-
Yes, Docutils now checks, whether the new "self.parent" after switching the section level is valid and reports these CRITICAL system messages (downgraded to ERROR in [r10198]. However, there is still a serious problem: an incompatibility with "qapidoc" rsp sphinx.util.nodes.nested_parse_with_titles(). This should be fixed in [r10200]. Can you re-try? If it still fails, please run with a "docutils.conf" file in the project directory that sets halt_level to 3? For added robustness, I recommend that...
-
Yes, Docutils now checks, whether the new "self.parent" after switching the section level is valid and reports these CRITICAL system messages (downgraded to ERROR in [r10198]. However, there is still a serious problem: an incompatibility with "qapidoc" rsp sphinx.util.nodes.nested_parse_with_titles(). This should be fixed in [r10200]. Can you re-try? For added robustness, I recommend that "qapidoc" switches from using sphinx.util.nodes.nested_parse_with_titles() to sphinx.util.parsing.nested_parse_to_nodes()...
-
In this case, the problem seems to be an incompatibility with Sphinx's "autoprogram". Can you please try with an updated repository version of Docutils? Commit [r10200] should fix it.
-
Fix error/crash whith Sphinx "autoprogram" [bugs:#509].
-
Restore accidentially deleted text in doctree documentation.
-
Fabien LOISON posted a comment on ticket #200
Ok, thank you for the answer :)
-
Relax "Unexpected section" system message from SEVERE to ERROR.
-
Add the gemini:// URI scheme
-
Thank you for the contribution. Unfortunately, we cannot include the patch without a change in the Docutils specification, https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#standalone-hyperlinks, which limits the supported URI schemes to the ones listed in the Official IANA Registry of URI Schemes and the W3C's Retired Index of WWW Addressing Schemes. While I don't see a "gemini" URI scheme as a particular problematic case, adding non-registered schemes should be done with special...
-
I've tried the attached patch, and with it, the qemu build succeeds, even without the patch I included above. There are still a lot of warnings: [6203/6204] Generating docs/QEMU manual with a custom command Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597. Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597. Possible...
-
Could you re-try with [r10197] or the attached patch if this gets a more telling log or and maybe some output?
-
Catch invalid node.parent when switching section levels.
-
What is strange, though is that Sphinx' autodoc extension does not have a problem with the new section parsing algorithm. Which extension does the extraction of docstrings rsp. the combination of the docstrings into a document?
-
This looks like the problem reported in [bugs:#508]. Could you check the Sphinx log? Do you use "autodoc" or similar extensions to extract docstrings?
-
You are right. As also seen in [#509], the CRITICAL errors are just on top of the problem (and helped to find the reasong beeing some "docstring reading" extension (plus docstrings that include section headings) beeing incompatible with Docutils 0.22. (Unfortunately, the new section algorithm was only tested with Sphinx, not with Sphinx extensions and docstrings containing section headings.)
-
Oliver Smith posted a comment on ticket #509
Do you use "autodoc" or similar extensions to extract docstrings? Yes, we use "sphinx.ext.autodoc". Could you check the Sphinx log? This is the output from Sphinx: Running Sphinx v8.2.3 loading translations [en]... done making output directory... done Converting `source_suffix = ['.rst', '.md']` to `source_suffix = {'.rst': 'restructuredtext', '.md': 'restructuredtext'}`. myst v4.0.1: MdParserConfig(commonmark_only=False, gfm_only=False, enable_extensions=set(), disable_syntax=[], all_links_external=False,...
-
Thank you for the analysis! When building qemu, I have the following sphinx packages installed: sphinxcontrib-applehelp-2.0.0 sphinxcontrib-devhelp-2.0.0 sphinxcontrib-htmlhelp-2.1.0 sphinxcontrib-jsmath-1.0.1 sphinxcontrib-qthelp-2.0.0 sphinxcontrib-serializinghtml-2.0.0 sphinx-8.2.3 sphinxcontrib-jquery-4.1 sphinx-rtd-theme-3.0.2 I think there might be second problem though. When I remove the whole comment that causes the CRITICAL errors, i.e. use the following diff: --- system/qtest.c.orig 2025-08-07...
-
This looks like the problem reported in [bugs:508]. Could you check the Sphinx log? Do you use "autodoc" or similar extensions to extract docstrings?
-
The reason is an incompatibility of Sphinx or one of the Sphinx extensions with the new section parsing algorithm introduced in commit [r10093] with updates in [r10129], [r10131], [r10131]. The unhelpful "TypeError" is displayed because Sphinx carries on after a CRITICAL problem which leads to follow-up problems (here, self.parent beeing None instead of an Element instance). The error reported by Docutils gives some hints. Let's dissect the first message: /scratch/emulators/qemu/work/qemu-10.0.3/docs/../system/qtest.c:70:...
-
More consistent and concise command line help.
-
regression with docutils 0.22: unsupported operand type(s) for +: 'NoneType' and 'list'
-
Test behaviour and fix documentation of rST footnotes.
-
qemu build problem after docutils update to 0.22
-
See also the discussion in Sphinx issue #8709. Use case: Changelogs of "pip" and "black" use version numbers as section titles: the auto-generated IDs are not stable but may change if a new section is inserted :( Workaround: "pip" uses explicit targets like "v25.1.1". This works in Sphinx, however, in Docutils, the "self-link" uses ids[0] which is the auto-generated one.
-
See also the discussion in Sphinx issue #8709.
-
See also [bugs:#207] (closed as a duplicate of this request).
-
Fix plural case of an error message.
-
Update reStructuredText Cheat Sheet.