docutils-users — General discussions, questions, help requests.

Re: [Docutils-users] A possible docutils' issue with certain IETF mailarchive URIs ?

[Viktor R. <vik...@gm...>]

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

[Docutils-users] A possible docutils' issue with certain IETF mailarchive URIs ?

[Viktor R. <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 ...

[Docutils-users] docutils 0.22rc5 release

[engelbert g. <eng...@gm...>]

Hei everyone,

only one change:

 Don't report an error for duplicate targets with identical refname

all the best
 e

[Docutils-users] release plan 0.22

[engelbert g. <eng...@gm...>]

Hei everyone,

today june 17th rc4 is out.

the final 0.22 is scheduled for end of july, start of august.

cheers
 e

[Docutils-users] docutils 0.22rc4

[engelbert g. <eng...@gm...>]

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

[Docutils-users] docutils 0.22rc3 is out

[engelbert g. <eng...@gm...>]

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

[Docutils-users] release 0.22rc2

[engelbert g. <eng...@gm...>]

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.

[Docutils-users] docutils 0.22 release plan changed

[engelbert g. <eng...@gm...>]

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

[Docutils-users] release 0.22rc1 is out

[engelbert g. <eng...@gm...>]

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_).

[Docutils-users] docutils 0.22 release plan

[engelbert g. <eng...@gm...>]

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

Re: [Docutils-users] Dealing with exception-based control flow in sections

[Guenter M. <mi...@us...>]

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?

[Docutils-users] Dealing with exception-based control flow in sections

[Arne S. <arn...@gm...>]

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

Re: [Docutils-users] Getting the reST source of a section node in a Sphinx extension

[Kayce B. <ka...@go...>]

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.
>

Re: [Docutils-users] Getting the reST source of a section node in a Sphinx extension

[Guenter M. <mi...@us...>]

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

Re: [Docutils-users] Getting the reST source of a section node in a Sphinx extension

[Kayce B. <ka...@go...>]

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,
>     }
>

[Docutils-users] Getting the reST source of a section node in a Sphinx extension

[Kayce B. <ka...@go...>]

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,
    }

Re: [Docutils-users] Adding a title attribute of reference in custom role

[Guenter M. <mi...@us...>]

Dear Wojciech,

On 2024-12-23, Wojciech Muła via Docutils-users wrote:

> I'm extending docutils to have shorter link. For example: :enwiki:`Docutils`
> expands into '<a href="https://en.wikipedia.org/Docutils>Docutils</a>'.
> I do that by using method `reference()`, like this:

> def enwiki_link_role(role, rawtext, text, lineno, inliner, options={}, content=[]):
>     set_classes(options)
>     ref, text = wikilink(text, 'en') # implementation detail
>     return [nodes.reference(rawtext, nodes.unescape(text), refuri=ref, **options)], []

> I want to add a title attribute, like '<a href=".." title="English
> Wikipedia on Docutils">...</a>'. Can't figure out how to do this, is it
> even possible?

In the `Docutils Document Format`__ (DocTree), the `"title" attribute`__
is only supported for the root element (<document>).

To get a HTML <a> element with a title, you would need to work around this
restriction:

* use "raw" HTML (https://docutils.sourceforge.io/docs/ref/doctree.html#raw)

* use a custom HTML writer that is able to write a "title" attribute for a
  <reference> DocTree element with either
  
  - a non-standard "title" attribute, or
  - a "special" class value (like "title-English-Wikipedia-on-Docutils")
  

Günter


__ https://docutils.sourceforge.io/docs/ref/docutils.dtd

https://docutils.sourceforge.io/docs/ref/doctree.html#title-1

[Docutils-users] Adding a title attribute of reference in custom role

[Wojciech M. <woj...@po...>]

Hi all!

I'm extending docutils to have shorter link. For example: :enwiki:`Docutils`
expands into '<a href="https://en.wikipedia.org/Docutils>Docutils</a>'.
I do that by using method `reference()`, like this:

def enwiki_link_role(role, rawtext, text, lineno, inliner, options={}, content=[]):
    set_classes(options)
    ref, text = wikilink(text, 'en') # implementation detail
    return [nodes.reference(rawtext, nodes.unescape(text), refuri=ref, **options)], []

I want to add a title attribute, like '<a href=".." title="English Wikipedia on Docutils">...</a>'.
Can't figure out how to do this, is it even possible?

Thanks!
I'm not a subscriber, please CC me.

regards
Wojciech

Re: [Docutils-users] Docutils sections

[Guenter M. <mi...@us...>]

On 2024-10-14, Jonathan Gossage wrote:

> [-- Type: text/plain, Encoding:  --]

> Currently, the method of identifying a section using a title with
> underlines and optional overlines does most of what I need in docutils. It
> generates the following HTML:
> * HTML <section> start
> * HTML section title
> * HTML Id modifier to uniquely identify a section.
> * HTML </section> to mark the end of a section.

> What it does not do is allow me to specify an HTML class. What I want to do
> is to style all sections differently depending on the level - h1 to h6 of
> the section. I have done this manually by modifying the generated HTML and
> therefore have a working verification of the concept.

Why don't you style the sections based on the level tag? ::

    <style>
      h1 {color: green;}
      h2 {color: red;}
      h3 {background: blue;}
      ...
    </style>


> A simple way to achieve this seems to be to create a new directive. That
> allows me to add a class specification as an option to the directive but I
> am hoping that there may be a simpler solution. Any suggestions?

The ``.. class::`` directive can be used to pass a class value to a section,
e.g. with the rST snippet::
 
  some text
 
  .. class:: funny
  
  A section
  *********

rst2html5 will generate::

  <p>some text</p>
  <section class="funny" id="a-section">
  <h2>A section<a class="self-link" title="link to this section" href="#a-section"></a></h2>
  <p>yes.</p>
  </section>


> P.S. I am using Docutils from Sphinx using Sphinx 7.4.

In this case, you will have to use ``.. rst-class::`` instead of 
``.. class::``.

Cf. https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#directives


Günter

[Docutils-users] Docutils sections

[Jonathan G. <jgo...@gm...>]

Currently, the method of identifying a section using a title with
underlines and optional overlines does most of what I need in docutils. It
generates the following HTML:
* HTML <section> start
* HTML section title
* HTML Id modifier to uniquely identify a section.
* HTML </section> to mark the end of a section.

What it does not do is allow me to specify an HTML class. What I want to do
is to style all sections differently depending on the level - h1 to h6 of
the section. I have done this manually by modifying the generated HTML and
therefore have a working verification of the concept.

A simple way to achieve this seems to be to create a new directive That
allows me to add a class specification as an option to the directive but I
am hoping that there may be a simpler solution. Any suggestions?

P.S. I am using Docutils from Sphinx using Sphinx 7.4.

-- 
Jonathan Gossage

[Docutils-users] Release 0.21.2 out

[engelbert g. <eng...@gm...>]

Very tiny release

trove classifier supports languages Georgian and Catalan (Valencian)
so does docutils

and test failure fix.

one week or so waiting time for bug reports
then ... on to 0.22

all the best
 e

[Docutils-users] release 0.21.2 post release on tuesday april 23

[engelbert g. <eng...@gm...>]

Release 0.21.2 consist of fix to tests
and support for languages Georgian and Catalan (Valencian)
both now in the pypi classifiers.

commit freeze till then and the week following for any problem reports

all the best
 e

[Docutils-users] release 0.21.1 fix sdist package

[engelbert g. <eng...@gm...>]

Good evening

Adding a 0.21.post1 in release 0.21 did not work

This made a new release necessary.
It could have been 0.21.post2, but this might be another problem ...

This is the first time I tested --no-binary ... and it only worked from pypi
not from test.pypi, but it worked.

sorry for any inconvenience
 e

[Docutils-users] Release 0.21

[engelbert g. <eng...@gm...>]

Hello to everyone,

Release 0.21 is out on pypi
  most of the work done by günter, kudos kudos kudos
  most of the fails on me

Release 0.21 (2024-04-09)
=========================

* General:

  - Drop support for Python 3.7 and 3.8.

  - Provide ``rst2*`` "console_scripts" `entry points`_
    (without the ``.py`` extension) instead of installing the
    ``rst2*.py`` `front end tools`_ in the binary PATH. [#]_

    Exceptions: ``rstpep2html.py`` and ``rst2odt_prepstyles.py``:

    - Use ``docutils --reader=pep --writer=pep_html`` for a PEP preview. [#]_
    - Use ``python -m docutils.writers.odf_odt.prepstyles``
      to `strip the page size`__ from an ODT writer stylesheet.

    __ docs/user/odt.html#page-size

  .. [#] Some Linux distributions already use the short names.
  .. [#] The final rendering is done by a Sphinx-based build system
         (cf. :PEP:`676`).

* reStructuredText:

  - Use the same CSV format for the ``:header:`` option and the main data
    of the "csv-table_" directive.

  - New option "loading" for the `"image" directive`_.
    Sets the new attribute loading__ of the <image> doctree element.

  __ docs/ref/doctree.html#loading

* Configuration changes:

  - New configuration setting root_prefix_.
    Configurable root directory for included files.

  - New configuration setting sources_ for the "buildhtml.py" application.

  - Simpler and more secure `input encoding`_ default behaviour:

    Do not use the locale encoding as fallback if Python is started in
    `UTF-8 mode`_. Stop using "latin1" as second fallback.

    Remove BOM (U+FEFF ZWNBSP at start of data) only if the `input_encoding`_
    configuration setting is None, '', 'utf-8-sig', 'utf-16', or 'utf-32'.
    Do not remove other ZWNBSPs.

* Output changes:

  HTML5:
    Stop setting the "footnote-reference" class value for footnote
    references. Use the CSS selector ``[role="doc-noteref"]``
    (works since Docutils 0.18, see minimal.css for examples).

    Fix MathML rendering problems in Chrome/Chromium based browsers.

    Embed SVG images as ``<svg>`` instead of data-URI.

  manpage:
    Use .EE/.EX macros for literal blocks.

    Render URI references (do not use .UR/.UE).

    Use box option for tables.

* Removed objects:

  `docutils.nodes.reprunicode`, `docutils.nodes.ensure_str()`
    Python 2 compatibility hacks
  `docutils.utils.Reporter.set_conditions()`
    obsolete
  `docutils.core.Publisher.setup_option_parser()`
    internal, obsolete

* New files:

  ``docutils/writers/html5_polyglot/italic-field-names.css``
    Alternative style for Docutils field-lists.

* Removed files:

  ``install.py``, ``setup.py``
    Metadata is now stored in ``pyproject.toml``,
    supported by pip_ since version 19.0 (2019-01-22).
    See README__ for installation alternatives.

  __ README.html#installation

* Bugfixes and improvements (see HISTORY_).

.. _input encoding: docs/api/publisher.html#encodings
.. _csv-table: docs/ref/rst/directives.html#csv-table
.. _"image" directive: docs/ref/rst/directives.html#image
.. _root_prefix: docs/user/config.html#root-prefix
.. _sources: docs/user/config.html#sources

Re: [Docutils-users] Incomplete unit listing

[Guenter M. <mi...@us...>]

Hi Anton,

thank you for the feedback.

On 2024-03-24, Anton Hvornum wrote:

> It appears there's some units missing from: 
> https://github.com/docutils/docutils/blob/b768e2626088711dec257b0847b563d02700a712/docutils/docutils/parsers/rst/directives/__init__.py#L240

> Namely: vh, vw, vmin, vmax, lvh, dvh, svw, lvw, dvw, svmin, lvmin, 
> dvmin, svmax, lvmax, dvmax, vi, svi, lvi, dvi, vb, svb, lvb and dvb

> These are part of the new HTML/CSS viewport units and are are/will be 
> part of CSS templates: 
> https://web.archive.org/web/20240114171725/https://www.terluinwebdesign.nl/en/css/incoming-20-new-css-viewport-units-svh-lvh-dvh-svw-lvw-dvw/

> If these are not compatible for some reason, perhaps they could be given 
> as a complementary argument to 
> https://github.com/docutils/docutils/blob/b768e2626088711dec257b0847b563d02700a712/docutils/docutils/parsers/rst/directives/__init__.py#L262C5-L262C23 
> for instance?

> I'm coming from a sphinx usage, where rendering HTML with CSS is the 
> base concept.

Did you see https://sourceforge.net/p/docutils/feature-requests/57/
"add vh and vw as allowable length units"?

In Docutils, we must take care to properly implement this for all supported
output formats (HTML, HTML4.1 + CSS1, LaTeX, ODT, manpages, XML)

This means we need to figure out what these units will be, e.g., on a
printed output or how to give adequate feedback if an output format does not
support the respective unit.

Suggestions welcome.

Günter