With the workaround, there is no longer an error but the caption is silently ignored.
A full fix would require changes to the code generating the document tree and maybe also to the
document model -- unless we can re-use some existing combination of nodes that combines a caption and a literal block.
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
Vale (https://github.com/errata-ai/vale) uses rst2html to parse rST files to apply style guides, and the lack of caption support for code blocks is causing it choke and start checking text within the code block (which it should not do). Is it possible to get caption support in rst2html?
If "vale" wants to support Sphinx extensions, using Sphinx
modules may be the better option.
When adding "caption" to the "code" directive in Docutils, we should
carefully consider how to represent a code block with caption in the
document tree (https://docutils.sourceforge.io/docs/ref/doctree.html), one
option would be a topic with title and code block. This can be
already achieved in a clean way by writing:
..topic:: example code
..code:: python
print("hello")
Ticket moved from /p/docutils/bugs/361/
Not a bug. Moved to Feature Requests.
Ok! This affects other packages too https://bugs.launchpad.net/doc8/+bug/1735779
Note, that the referenced doc8 bug references Sphinx documentation.
Sphinx builds on Docutils adding syntax.
The "code" directive in Docutils has only the options "name", "class", and "number-lines".
http://docutils.sourceforge.net/docs/ref/rst/directives.html#code
I do not know whether doc8 uses Sphinx or Docutils and hence whether
docutilsdependency" is wrong.Hi @Gunter, and thanks for your reply.
I eventually made a workaround on a patched version of
docutilshere: https://github.com/ioggstream/docutils/commit/4a8f9277e1ff1c5929a7b9b42d828a5c14e806b9What is needed for that to be supported into docutils?
With the workaround, there is no longer an error but the caption is silently ignored.
A full fix would require changes to the code generating the document tree and maybe also to the
document model -- unless we can re-use some existing combination of nodes that combines a caption and a literal block.
Vale (https://github.com/errata-ai/vale) uses rst2html to parse rST files to apply style guides, and the lack of caption support for code blocks is causing it choke and start checking text within the code block (which it should not do). Is it possible to get caption support in rst2html?
https://www.sphinx-doc.org/en/1.4.9/markup/code.html#caption-and-name
The "caption" option of the
code-blockdirective is one of severalextensions made by Sphinx to the rST syntax (compare
https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html
and https://docutils.sourceforge.io/docs/ref/rst/directives.html).
If "vale" wants to support Sphinx extensions, using Sphinx
modules may be the better option.
When adding "caption" to the "code" directive in Docutils, we should
carefully consider how to represent a code block with caption in the
document tree (https://docutils.sourceforge.io/docs/ref/doctree.html), one
option would be a topic with title and code block. This can be
already achieved in a clean way by writing:
in the rST source.
See also the ideas for a "literal" directive
and generic "float" elements in the Docutils TODO list.
https://docutils.sourceforge.io/docs/dev/todo.html#body-literal
Last edit: Günter Milde 2025-04-29