docutils-develop Mailing List for Docutils: Documentation Utilities (Page 10)

Has docutils.writers.latex2e.SortableDict rather recently been replaced
with an ordinary dict somewhere?
Thanks, Alan Isaac

- **assigned_to**: Günter Milde -->  nobody 
- **Group**:  --> Default



---

**[feature-requests:#110] Move from "optparse" to "argparse".**

**Status:** open
**Group:** Default
**Created:** Thu Jan 06, 2022 03:02 PM UTC by Günter Milde
**Last Updated:** Sat Oct 19, 2024 10:10 AM UTC
**Owner:** nobody


The optparse documentation says:
> Deprecated since version 3.2: The optparse module is deprecated and will not be developed further; development will continue with the argparse module.

We are currently suppressing related deprecation warnings in the test suite.
After raising the Python dependency to >=3.7, now may be the right time to make the move.


---

Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/feature-requests/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/feature-requests/options.  Or, if this is a mailing list, you can unsubscribe from the mailing list.

See also the proposal by Roman Suzi in "docutils-users" from 2003-07-07.
https://sourceforge.net/p/docutils/mailman/docutils-users/thread/Pine.LNX.4.44.0307070819150.2138-100000%40rnd.onego.ru/#msg4465479



---

**[feature-requests:#108] "title" option for the "image" directive**

**Status:** pending-works-for-me
**Group:** Default
**Created:** Sun Sep 29, 2024 08:41 AM UTC by toastal
**Last Updated:** Thu Oct 17, 2024 08:23 PM UTC
**Owner:** nobody


Like `image`’s `:alt:` directive, allow `:title:` for creating titles on pointer hover. The use case here is different from alt as alt is for assistive technologies & titles are more to give a labels for images for those with pointer cursors.

Expected input

~~~
.. image:: /house.jxl
	:alt: Home
	:title: Navigate home
	:target: /

.. image:: /cat.jxl
	:alt: A Siamese cat on a chair
	:title: Chula says, “meow”
~~~

Expected HTML output

~~~
<a href="/"><img src="/house.jxl" alt="Home" title="Navigate home"></a>
<img src="/cat.jxl" alt="A Siamese cat on a chair" title="Chula says, “meow”">
~~~

~~~






---

Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/feature-requests/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/feature-requests/options.  Or, if this is a mailing list, you can unsubscribe from the mailing list.

- **status**: open --> open-fixed
- **Comment**:

SVG support via the "svg" LaTeX package is implemented in [r9999].



---

**[feature-requests:#83] Support SVG images in LaTeX**

**Status:** open-fixed
**Group:** Default
**Created:** Sat Oct 09, 2021 12:05 AM UTC by Local State
**Last Updated:** Wed Jun 01, 2022 10:02 PM UTC
**Owner:** nobody


Hi there, this is Local State.

## Motivation
The current `Image` directive is not enough for svg files. Using `img` tag loses interactivities, and the width, and height can't be applied for svg files directly. It's better to use `style="width:50%"` instead. 

## 2 New Options
I'm hoping there could be 2 new options for `Image` directive.
    
   1. `tag`
        This would determine the html tag used to render the image. The default value would be `img`, and we could also use `object`, `iframe` and `embed` as alternatives. Currently, all images are rendered with `img` tag, which loses some interactivities (e.g., the text in svg file). We could avoid this by using `object` tag. I see there are some similar work in `html4css1` about `object_image_types`.  
        
        Example:
        ```
        <img src="a.png" width="50%" alt="alt msg">`
        <object data="a.png" style="width:50%">alt msg</object>
        <iframe src="a.png" width="50%" title="alt msg"></iframe>
        <embed src="a.png" width="50%">`
        ```
        
   2. `embed`
        If enabled, this option would embed the image into the html file using base64 encoding.  
        While I see there is already the if sentence in the `visit_image` function.
        ```
        if self.settings.embed_images or ('embed' in node):
        ```
        The `embed_images` could be set from command-line or setting, but I can't find how to satisfy the latter condition, since any node doesn't seem to have `embed` attribute. Could anyone tell me how to enable it? If we can't, then it's necessary to add the `embed` option, so that we could choose to embed one particular image or not. 
        Especially, I notice there exist a `todo` item for svg embedding. I'd like to implement it if possible. But the first option is still in demand, because most times we don't want our html files to be so large and need separate svg files.

##  Potential bugs
 
 svg files under `<img>` tag can't correctly render height and width if svg viewbox information is not contained in the file. It might be better to set the height and width in `style` indirectly.

##  Contribution
 I would like to fix and implement all these things if possible. But I'm not quite familiar with SourceForge and don't know how to submit a PR like what we do in github.


---

Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/feature-requests/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/feature-requests/options.  Or, if this is a mailing list, you can unsubscribe from the mailing list.

A helper function that converts a URI-reference to a filesystem path for HTML and LaTeX writers based on this patch is introduced in [r9996]. The ODT writer will have to wait, as this is a backwards-incompatible change: : The ODT writer expects relative image paths to be relative to the *source* directory. 


---

**[bugs:#493] Test failure on Windows with embedded images**

**Status:** pending-works-for-me
**Created:** Wed Aug 07, 2024 02:25 AM UTC by Adam  Turner
**Last Updated:** Mon Nov 25, 2024 09:08 PM UTC
**Owner:** nobody


xref [r9785], [r9853], [r9855]

Dear @milde,

Thank you for the fix to my recent patch. It seems neither my patch nor the fix addressed the root cause of the test failures, as tests have resumed failing on Windows.

I believe the following demonstrates the problem:

```pycon
>>> import sys; print(sys.platform)
win32
>>> import urllib.parse, urllib.request
>>> urllib.request.url2pathname('test/data/circle-broken.svg')
'test\\data\\circle-broken.svg'
>>> urllib.parse.unquote('test/data/circle-broken.svg')
'test/data/circle-broken.svg'
```

Currently, we use `imagepath = urllib.request.url2pathname(uri_parts.path)`, which converts path separators to their platform-native format. On UNIX, `url2pathname` simply calls `unquote`, but on Windows it handles UNC paths (``\\host\path\``) and escaped drive letters (``///C|/users/``).

I don't know what led to using `url2pathname()`, as it is quite specialised (the docstring notes "not recommended for general use"). Is it possible to use the simpler `unquote()` here?  

For local file paths (e.g. without a ``file:///`` scheme), should we even be using URI parsing? Perhaps we should use proper path handling if there is no URI scheme (i.e. the user has provided a file-path).

A


---

Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/bugs/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/bugs/options.  Or, if this is a mailing list, you can unsubscribe from the mailing list.

Sorry I wasn't able to test the patch in a timely manner. Thanks for the fix!


---

**[bugs:#494] rst2odt: TypeError with --stylesheet=styles.xml**

**Status:** open-fixed
**Labels:** ODT Writer 
**Created:** Fri Oct 04, 2024 10:52 AM UTC by Paul Kishimoto
**Last Updated:** Sun Oct 20, 2024 05:46 PM UTC
**Owner:** nobody


The documentation (page “ODT Writer for Docutils”, section [“4 Styles and Classes”](https://docutils.sourceforge.io/docs/user/odt.html#styles-and-classes)) states:
> Note that with the `--stylesheet` command line option, you can use either `styles.odt` or `styles.xml`, as described below. Use of `styles.odt` is recommended over `styles.xml`.

With Python 3.12.3 and docutils 0.21.2, it appears that styles.xml is not usable, either from the command line or programmatically.

To reproduce from the command line:
1. A file `empty.rst`.
2. A file `styles.xml`, extracted from any valid ODT archive.
3. Run `$ docutils --writer=odt --stylesheet=styles.xml --traceback empty.rst >bug.odt`

The output is:
```
Traceback (most recent call last):
  File "/home/khaeru/.venv/3.12/bin/docutils", line 8, in <module>
    sys.exit(main())
             ^^^^^^
  File "/home/khaeru/.venv/3.12/lib/python3.12/site-packages/docutils/__main__.py", line 78, in main
    publish_cmdline(reader_name=args.reader,
  File "/home/khaeru/.venv/3.12/lib/python3.12/site-packages/docutils/core.py", line 402, in publish_cmdline
    output = publisher.publish(
             ^^^^^^^^^^^^^^^^^^
  File "/home/khaeru/.venv/3.12/lib/python3.12/site-packages/docutils/core.py", line 237, in publish
    output = self.writer.write(self.document, self.destination)
             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/khaeru/.venv/3.12/lib/python3.12/site-packages/docutils/writers/__init__.py", line 80, in write
    self.translate()
  File "/home/khaeru/.venv/3.12/lib/python3.12/site-packages/docutils/writers/odf_odt/__init__.py", line 510, in translate
    self.visitor.retrieve_styles(self.EXTENSION)
  File "/home/khaeru/.venv/3.12/lib/python3.12/site-packages/docutils/writers/odf_odt/__init__.py", line 941, in retrieve_styles
    self.dom_stylesheetcontent = etree.fromstring(
                                 ^^^^^^^^^^^^^^^^^
  File "/usr/lib/python3.12/xml/etree/ElementTree.py", line 1335, in XML
    parser.feed(text)
TypeError: a bytes-like object is required, not 'NoneType'
```

The same error occurs when calling:
```python
from docutils.core import publish_string

publish_string(
    source="",
    writer_name="odt",
    settings_overrides={"stylesheet": "styles.xml"},
)
```

This seems to be a consequence of `ODFTranslator.retrieve_styles()` ([here](https://sourceforge.net/p/docutils/code/HEAD/tree/trunk/docutils/docutils/writers/odf_odt/__init__.py#l925)), wherein:

1. `s2 = None` is set.
2. If the provided path has extension `extension` (e.g. ".odt"), it is overwritten with content read from `content.xml` in the archive; **but** if the provided path has extension ".xml", it remains `None`.
3. This value is assigned to `self.str_stylesheetcontent` and then parsed with `etree.tostring()`.

Also, the parsed `self.dom_stylesheetcontent` does not appear to be used anywhere else in the module. It's not clear why it is needed.


---

Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/bugs/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/bugs/options.  Or, if this is a mailing list, you can unsubscribe from the mailing list.

This part of the patch is applied in [r9991].


---

**[bugs:#493] Test failure on Windows with embedded images**

**Status:** pending-works-for-me
**Created:** Wed Aug 07, 2024 02:25 AM UTC by Adam  Turner
**Last Updated:** Tue Oct 15, 2024 09:44 PM UTC
**Owner:** nobody


xref [r9785], [r9853], [r9855]

Dear @milde,

Thank you for the fix to my recent patch. It seems neither my patch nor the fix addressed the root cause of the test failures, as tests have resumed failing on Windows.

I believe the following demonstrates the problem:

```pycon
>>> import sys; print(sys.platform)
win32
>>> import urllib.parse, urllib.request
>>> urllib.request.url2pathname('test/data/circle-broken.svg')
'test\\data\\circle-broken.svg'
>>> urllib.parse.unquote('test/data/circle-broken.svg')
'test/data/circle-broken.svg'
```

Currently, we use `imagepath = urllib.request.url2pathname(uri_parts.path)`, which converts path separators to their platform-native format. On UNIX, `url2pathname` simply calls `unquote`, but on Windows it handles UNC paths (``\\host\path\``) and escaped drive letters (``///C|/users/``).

I don't know what led to using `url2pathname()`, as it is quite specialised (the docstring notes "not recommended for general use"). Is it possible to use the simpler `unquote()` here?  

For local file paths (e.g. without a ``file:///`` scheme), should we even be using URI parsing? Perhaps we should use proper path handling if there is no URI scheme (i.e. the user has provided a file-path).

A


---

Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/bugs/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/bugs/options.  Or, if this is a mailing list, you can unsubscribe from the mailing list.

- **labels**: harmful deprecation --> 
- **status**: open --> closed
- **Comment**:

It seems the proposed change did the trick.

So for the relevant use case there is a replacement and it seems rather like an "incomplete documentation" problem -- which is hopefully fixed by [r9990].

Thanks for reporting.




---

**[bugs:#496] OptionParser deprecated without replacement makes Sphinx extensions crash in strict mode**

**Status:** closed
**Created:** Wed Nov 20, 2024 10:13 PM UTC by Sviatoslav Sydorenko
**Last Updated:** Mon Nov 25, 2024 02:25 PM UTC
**Owner:** nobody


Per best practice, many people run Sphinx with `-n -W --keep-going`. Plus the interpreter itself may be called with `-Werror`. This turns any warnings into errors, making sure that no problems or future deprecations will go unnoticed.
The typical situation is when a dependency updates, it emits a deprecation warning and we can address said warning by doing what it says and starting to use some new API. This is happening together with the version bump so it never breaks CI.
Things are different with docutils, though. When I was integrating `sphinx-autodoc-typehints` into well-established codebase, I started getting a traceback, breaking the docs builds.

I wasn't the first one to hit it: https://github.com/tox-dev/sphinx-autodoc-typehints/issues/454.

When I saw the deprecation message, I was expecting the usual process. I thought that I'd contribute a bit of compatibility code into `sphinx-autodoc-typehints` and be done with it.

I tracked it down to https://github.com/docutils/docutils/commit/6548b56d9ea9a3e101cd62cfcd727b6e9e8b7ab6#diff-d1f841500d12a20b000229849c98cd38d8fe4d0ab5a149119244931969ee82e3R659 and what I saw caught me by surprise — the was no replacement. The deprecation warning is emitted but in a way that it's impossible to react to it in any reasonable manner. It says that `docutils.frontend.OptionParser` is not supposed to be used anymore but does not offer any way forward. It's a stalemate.

So here I am, writing this bug report in hopes that the depecation warning would be dropped or the replacement added. I argue that this use of deprecation warnings is incorrect. It's not even a `FutureDeprecationWarning`. It's something that is stated to be deprecated already, right now, today, two years ago even.


---

Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/bugs/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/bugs/options.  Or, if this is a mailing list, you can unsubscribe from the mailing list.

I understand that breaking long-standing APIs is not an option. I was merely suggesting doing this for new things.


---

**[bugs:#496] OptionParser deprecated without replacement makes Sphinx extensions crash in strict mode**

**Status:** open
**Labels:** harmful deprecation 
**Created:** Wed Nov 20, 2024 10:13 PM UTC by Sviatoslav Sydorenko
**Last Updated:** Mon Nov 25, 2024 11:39 AM UTC
**Owner:** nobody


Per best practice, many people run Sphinx with `-n -W --keep-going`. Plus the interpreter itself may be called with `-Werror`. This turns any warnings into errors, making sure that no problems or future deprecations will go unnoticed.
The typical situation is when a dependency updates, it emits a deprecation warning and we can address said warning by doing what it says and starting to use some new API. This is happening together with the version bump so it never breaks CI.
Things are different with docutils, though. When I was integrating `sphinx-autodoc-typehints` into well-established codebase, I started getting a traceback, breaking the docs builds.

I wasn't the first one to hit it: https://github.com/tox-dev/sphinx-autodoc-typehints/issues/454.

When I saw the deprecation message, I was expecting the usual process. I thought that I'd contribute a bit of compatibility code into `sphinx-autodoc-typehints` and be done with it.

I tracked it down to https://github.com/docutils/docutils/commit/6548b56d9ea9a3e101cd62cfcd727b6e9e8b7ab6#diff-d1f841500d12a20b000229849c98cd38d8fe4d0ab5a149119244931969ee82e3R659 and what I saw caught me by surprise — the was no replacement. The deprecation warning is emitted but in a way that it's impossible to react to it in any reasonable manner. It says that `docutils.frontend.OptionParser` is not supposed to be used anymore but does not offer any way forward. It's a stalemate.

So here I am, writing this bug report in hopes that the depecation warning would be dropped or the replacement added. I argue that this use of deprecation warnings is incorrect. It's not even a `FutureDeprecationWarning`. It's something that is stated to be deprecated already, right now, today, two years ago even.


---

Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/bugs/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/bugs/options.  Or, if this is a mailing list, you can unsubscribe from the mailing list.

Thanks for the info.  Please try replacing
~~~ diff
- from docutils.frontend import OptionParser
+ from docutils.frontend import get_default_settings
~~~
and
~~~ diff
- settings = OptionParser(components=(RSTParser,)).get_default_values()
+ settings = get_default_settings(RSTParser)
~~~

> may I suggest keeping private API in underscored modules?

The "frontend" module and `frontend.OptionParser` are from 2002, predating the inclusion of "optparse" into the Python standard library in Python 2.3.  and 9 years before active development switched to "argparse".  Renaming with an underscore now would cause significantly more disruption than a deprecation warning. 
In order to prepare for the transition to "argparse", `docutils.frontend` became classed as "provisional" in Docutils 0.19. Applications should use the high-level API provided by `docutils.core`.





---

**[bugs:#496] OptionParser deprecated without replacement makes Sphinx extensions crash in strict mode**

**Status:** open
**Labels:** harmful deprecation 
**Created:** Wed Nov 20, 2024 10:13 PM UTC by Sviatoslav Sydorenko
**Last Updated:** Sat Nov 23, 2024 11:01 PM UTC
**Owner:** nobody


Per best practice, many people run Sphinx with `-n -W --keep-going`. Plus the interpreter itself may be called with `-Werror`. This turns any warnings into errors, making sure that no problems or future deprecations will go unnoticed.
The typical situation is when a dependency updates, it emits a deprecation warning and we can address said warning by doing what it says and starting to use some new API. This is happening together with the version bump so it never breaks CI.
Things are different with docutils, though. When I was integrating `sphinx-autodoc-typehints` into well-established codebase, I started getting a traceback, breaking the docs builds.

I wasn't the first one to hit it: https://github.com/tox-dev/sphinx-autodoc-typehints/issues/454.

When I saw the deprecation message, I was expecting the usual process. I thought that I'd contribute a bit of compatibility code into `sphinx-autodoc-typehints` and be done with it.

I tracked it down to https://github.com/docutils/docutils/commit/6548b56d9ea9a3e101cd62cfcd727b6e9e8b7ab6#diff-d1f841500d12a20b000229849c98cd38d8fe4d0ab5a149119244931969ee82e3R659 and what I saw caught me by surprise — the was no replacement. The deprecation warning is emitted but in a way that it's impossible to react to it in any reasonable manner. It says that `docutils.frontend.OptionParser` is not supposed to be used anymore but does not offer any way forward. It's a stalemate.

So here I am, writing this bug report in hopes that the depecation warning would be dropped or the replacement added. I argue that this use of deprecation warnings is incorrect. It's not even a `FutureDeprecationWarning`. It's something that is stated to be deprecated already, right now, today, two years ago even.


---

Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/bugs/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/bugs/options.  Or, if this is a mailing list, you can unsubscribe from the mailing list.

The exact place in said plugin is linked in the issue I mentioned in the original post: https://github.com/tox-dev/sphinx-autodoc-typehints/issues/454#issuecomment-2489588907.

It's here: https://github.com/tox-dev/sphinx-autodoc-typehints/blob/ffea355/src/sphinx_autodoc_typehints/__init__.py#L840-L848 


---

**[bugs:#496] OptionParser deprecated without replacement makes Sphinx extensions crash in strict mode**

**Status:** open
**Labels:** harmful deprecation 
**Created:** Wed Nov 20, 2024 10:13 PM UTC by Sviatoslav Sydorenko
**Last Updated:** Sat Nov 23, 2024 09:53 PM UTC
**Owner:** nobody


Per best practice, many people run Sphinx with `-n -W --keep-going`. Plus the interpreter itself may be called with `-Werror`. This turns any warnings into errors, making sure that no problems or future deprecations will go unnoticed.
The typical situation is when a dependency updates, it emits a deprecation warning and we can address said warning by doing what it says and starting to use some new API. This is happening together with the version bump so it never breaks CI.
Things are different with docutils, though. When I was integrating `sphinx-autodoc-typehints` into well-established codebase, I started getting a traceback, breaking the docs builds.

I wasn't the first one to hit it: https://github.com/tox-dev/sphinx-autodoc-typehints/issues/454.

When I saw the deprecation message, I was expecting the usual process. I thought that I'd contribute a bit of compatibility code into `sphinx-autodoc-typehints` and be done with it.

I tracked it down to https://github.com/docutils/docutils/commit/6548b56d9ea9a3e101cd62cfcd727b6e9e8b7ab6#diff-d1f841500d12a20b000229849c98cd38d8fe4d0ab5a149119244931969ee82e3R659 and what I saw caught me by surprise — the was no replacement. The deprecation warning is emitted but in a way that it's impossible to react to it in any reasonable manner. It says that `docutils.frontend.OptionParser` is not supposed to be used anymore but does not offer any way forward. It's a stalemate.

So here I am, writing this bug report in hopes that the depecation warning would be dropped or the replacement added. I argue that this use of deprecation warnings is incorrect. It's not even a `FutureDeprecationWarning`. It's something that is stated to be deprecated already, right now, today, two years ago even.


---

Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/bugs/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/bugs/options.  Or, if this is a mailing list, you can unsubscribe from the mailing list.

The docutils OptionParser class is not intended for direct use -- code using  Docutils as a library is supposed to work with the provided API functions  instead.

Could you be more specific about the situation that led to the warning? With a minimal working example showing the problem and a traceback, we may help finding the right replacement code.


---

**[bugs:#496] OptionParser deprecated without replacement makes Sphinx extensions crash in strict mode**

**Status:** open
**Labels:** harmful deprecation 
**Created:** Wed Nov 20, 2024 10:13 PM UTC by Sviatoslav Sydorenko
**Last Updated:** Wed Nov 20, 2024 10:13 PM UTC
**Owner:** nobody


Per best practice, many people run Sphinx with `-n -W --keep-going`. Plus the interpreter itself may be called with `-Werror`. This turns any warnings into errors, making sure that no problems or future deprecations will go unnoticed.
The typical situation is when a dependency updates, it emits a deprecation warning and we can address said warning by doing what it says and starting to use some new API. This is happening together with the version bump so it never breaks CI.
Things are different with docutils, though. When I was integrating `sphinx-autodoc-typehints` into well-established codebase, I started getting a traceback, breaking the docs builds.

I wasn't the first one to hit it: https://github.com/tox-dev/sphinx-autodoc-typehints/issues/454.

When I saw the deprecation message, I was expecting the usual process. I thought that I'd contribute a bit of compatibility code into `sphinx-autodoc-typehints` and be done with it.

I tracked it down to https://github.com/docutils/docutils/commit/6548b56d9ea9a3e101cd62cfcd727b6e9e8b7ab6#diff-d1f841500d12a20b000229849c98cd38d8fe4d0ab5a149119244931969ee82e3R659 and what I saw caught me by surprise — the was no replacement. The deprecation warning is emitted but in a way that it's impossible to react to it in any reasonable manner. It says that `docutils.frontend.OptionParser` is not supposed to be used anymore but does not offer any way forward. It's a stalemate.

So here I am, writing this bug report in hopes that the depecation warning would be dropped or the replacement added. I argue that this use of deprecation warnings is incorrect. It's not even a `FutureDeprecationWarning`. It's something that is stated to be deprecated already, right now, today, two years ago even.


---

Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/bugs/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/bugs/options.  Or, if this is a mailing list, you can unsubscribe from the mailing list.

---

**[bugs:#496] OptionParser deprecated without replacement makes Sphinx extensions crash in strict mode**

**Status:** open
**Labels:** harmful deprecation 
**Created:** Wed Nov 20, 2024 10:13 PM UTC by Sviatoslav Sydorenko
**Last Updated:** Wed Nov 20, 2024 10:13 PM UTC
**Owner:** nobody


Per best practice, many people run Sphinx with `-n -W --keep-going`. Plus the interpreter itself may be called with `-Werror`. This turns any warnings into errors, making sure that no problems or future deprecations will go unnoticed.
The typical situation is when a dependency updates, it emits a deprecation warning and we can address said warning by doing what it says and starting to use some new API. This is happening together with the version bump so it never breaks CI.
Things are different with docutils, though. When I was integrating `sphinx-autodoc-typehints` into well-established codebase, I started getting a traceback, breaking the docs builds.

I wasn't the first one to hit it: https://github.com/tox-dev/sphinx-autodoc-typehints/issues/454.

When I saw the deprecation message, I was expecting the usual process. I thought that I'd contribute a bit of compatibility code into `sphinx-autodoc-typehints` and be done with it.

I tracked it down to https://github.com/docutils/docutils/commit/6548b56d9ea9a3e101cd62cfcd727b6e9e8b7ab6#diff-d1f841500d12a20b000229849c98cd38d8fe4d0ab5a149119244931969ee82e3R659 and what I saw caught me by surprise — the was no replacement. The deprecation warning is emitted but in a way that it's impossible to react to it in any reasonable manner. It says that `docutils.frontend.OptionParser` is not supposed to be used anymore but does not offer any way forward. It's a stalemate.

So here I am, writing this bug report in hopes that the depecation warning would be dropped or the replacement added. I argue that this use of deprecation warnings is incorrect. It's not even a `FutureDeprecationWarning`. It's something that is stated to be deprecated already, right now, today, two years ago even.


---

Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/bugs/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/bugs/options.  Or, if this is a mailing list, you can unsubscribe from the mailing list.

- **status**: open --> closed-fixed
- **Comment**:

All open decisions are solved. 
Backwards-incompatible changes are announced and will be implemented over the next releases.



---

**[bugs:#489] Issues with the Docutils Doctree**

**Status:** closed-fixed
**Created:** Tue Jun 11, 2024 12:13 PM UTC by Günter Milde
**Last Updated:** Sun Jul 28, 2024 10:52 AM UTC
**Owner:** nobody


There are a number of discrepancies between the [Docutils Generic DTD][docutils.dtd]
and the implementation in Docutils code.

footnote
--------

[docutils.dtd][docutils.dtd]: `(label?, (%body.elements;)+)`
→ Label **optional**, content **required**; (not changed since 2002-04-20).

[reStructureText Markup Specification][rST spec]:
> Each footnote consists of an explicit markup start (".. "), a left
> square bracket, **the footnote label**, a right square bracket, and
> whitespace, followed by indented body elements.

The `footnote` class in [docutils.nodes](https://docutils.sourceforge.io/docutils/nodes.py) is a subclass of `Labeled`, 
whose docstring says: "**Contains a label** as its first element."

The rST parser **requires** a label but allows **empty footnotes**
(cf. `test/test_writers/test_latex2e.py`).

citation
--------

[docutils.dtd][docutils.dtd]: `(label, (%body.elements;)+)`
→ Label **required**, content **required**; (not changed since 2002-04-20).

[reStructureText Markup Specification][rST spec]:
> Citations are **identical to footnotes** except that they use only
> non-numeric labels …

The rST parser allows **empty citations** (cf. test_rst/test_citations.py).

figure
------

[docutils.dtd][docutils.dtd]: `(image, ((caption, legend?) | legend))`
→ caption or legend **required**; (not changed since 2002-04-20).

[reStructuredText Directives](https://docutils.sourceforge.io/docs/ref/rst/directives.html#figure)

> A "figure" consists of image data (including image options), an **optional
> caption** (a single paragraph), and an **optional legend** (arbitrary body
> elements). For page-based output media, figures might float to a different
> position if this helps the page layout.

The rST parser allows **figures without caption or legend**.

Docutils HTML and LaTeX writers use a different layout for figures vs.
images. They can handle figures without caption/legend.

Suggestion
----------

* Make *footnote label compulsory`*.
* Let rST report a *warning for empty footnote and citation*.
  Remove tests with empty footnote and citation.
* Allow *figures without caption/legend* in the Docutils Generic DTD.

(Change in Docutils 1.0, announce in 0.22.)

Questions
---------
Are there a use cases for 
* footnotes without label,
* footnotes without content,
* citations without content?

[docutils.dtd]: https://docutils.sourceforge.io/docs/ref/docutils.dtd
[rST spec]: https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html



---

Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/bugs/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/bugs/options.  Or, if this is a mailing list, you can unsubscribe from the mailing list.

- **status**: open --> open-accepted
- **Comment**:

Applied in  [r9979]. Thank you for the patch.



---

**[patches:#211] Doctest nodes have incorrect `line` field **

**Status:** open-accepted
**Group:** None
**Created:** Thu Sep 12, 2024 09:39 AM UTC by Hood Chatham
**Last Updated:** Thu Sep 12, 2024 09:47 AM UTC
**Owner:** nobody


For most nodes, `node.line` refers to the source line that the node started on. However, doctest nodes report the end line. 

This can be fixed with the following patch:
```patch
--- a/docutils/docutils/parsers/rst/states.py
+++ b/docutils/docutils/parsers/rst/states.py
@@ -1587,11 +1587,14 @@ def parse_option_marker(self, match):
         return optlist
 
     def doctest(self, match, context, next_state):
+        line = self.document.current_line
         data = '\n'.join(self.state_machine.get_text_block())
         # TODO: prepend class value ['pycon'] (Python Console)
         # parse with `directives.body.CodeBlock` (returns literal-block
         # with class "code" and syntax highlight markup).
-        self.parent += nodes.doctest_block(data, data)
+        n = nodes.doctest_block(data, data)
+        n.line = line
+        self.parent += n
         return [], next_state, []
 
     def line_block(self, match, context, next_state):
```



---

Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/patches/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/patches/options.  Or, if this is a mailing list, you can unsubscribe from the mailing list.

- **status**: open --> pending-remind



---

**[patches:#210] Typing and `docutils.nodes.Node`**

**Status:** pending-remind
**Group:** None
**Created:** Thu Aug 15, 2024 08:38 AM UTC by Adam  Turner
**Last Updated:** Thu Aug 15, 2024 02:13 PM UTC
**Owner:** nobody


Commit [r9901] by @milde changes instances of `Element | Text` to `Node`, and adds attributes to `Node`. I think that this is a not the best and the commit should be reverted before the impending 0.22 release, to allow for more discussion.

As I noted in commit [r9813] which added type hints:

```text
Add type hints to ``docutils.nodes``

A significant number of parameters and attributes are typed as
expecting or yielding ``Element | Text`` rather than ``Node``,
which is the more obvious choice. This union type is used because
``Node`` is de facto an abstract base class --- it should not
be used or instantiated. Notably, ``Node.children`` is not defined,
``Node.attributes`` does not exist, etc. The two direct subclasses
fill in many of these missing pieces, making static typing both
more precise and easier.
```

``Element`` and ``Text`` are different types, as `Text` can be treated as a string and `Element` means that we have a concrete node type with attributes and data. Conflating these as `Node` is unhelpful, and we shouldn't signal to users that a `Node` is expected anywhere, as whilst is is *de facto* an abstract base class, it can be instantiated and used at runtime, which should be heavily discouraged.

Aside from verbosity, I'm unsure of the argument to change this. Verbosity can be managed with a type alias, as we had previously used (`ElementT`, though this should perhaps be named `ElementOrText`).

A


---

Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/patches/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/patches/options.  Or, if this is a mailing list, you can unsubscribe from the mailing list.

- **status**: open --> pending-moreinfo



---

**[patches:#179] Add option to place captions above figure**

**Status:** pending-moreinfo
**Group:** None
**Created:** Mon Jan 18, 2021 07:35 PM UTC by Jesse Tan
**Last Updated:** Thu Jan 28, 2021 09:08 PM UTC
**Owner:** nobody
**Attachments:**

- [figure-caption-top.patch](https://sourceforge.net/p/docutils/patches/179/attachment/figure-caption-top.patch) (2.0 kB; application/octet-stream)


Figures currently have a caption below the figure. This patch adds a config option that allows placement above the figure.
Documentation is added, but no test. Tips on how to progress would be appreciated.


---

Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/patches/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/patches/options.  Or, if this is a mailing list, you can unsubscribe from the mailing list.

- **labels**:  --> ODT Writer



---

**[bugs:#468] New release of libpaper (paperconf) does not work with rst2odt**

**Status:** pending-remind
**Labels:** ODT Writer 
**Created:** Wed Mar 08, 2023 10:59 AM UTC by fouinix
**Last Updated:** Fri May 12, 2023 03:50 PM UTC
**Owner:** nobody


Hello,
It seems a new release of libpaper has broken rst2odt. `paperconf -s` no longer exists:

~~~
paperconf -s 
(null): unknown option ‘-s’
~~~


---

Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/bugs/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/bugs/options.  Or, if this is a mailing list, you can unsubscribe from the mailing list.

- **status**: open --> closed-fixed
- **Comment**:

Done in [r9977].



---

**[feature-requests:#109] Drop outdated copy of roman.py in docutils/utils**

**Status:** closed-fixed
**Group:** Default
**Created:** Fri Oct 04, 2024 09:17 AM UTC by Günter Milde
**Last Updated:** Tue Oct 15, 2024 09:39 PM UTC
**Owner:** nobody


Back in the days without pypi and pip, Docutils developers decided to ship a copy of the small auxiliary module  [roman.py](https://pypi.org/project/roman/)  with Docutils in order to allow the package to stay free of any dependencies except Python (also a pre-requisite for the proposed inclusion of Docutils into the standard library).

In the year 2024, however, depending on an external module that 

* is available on pip, 
* has no other dependencies, and 
* is maintained 
 
should not pose an obstacle to Docutils users.

Commits  [r9845] and [r9846] added and adopted an alternative implementation of Roman  numeral support but did not remove the copy of the upstream `roman.py`.

I propose to remove both, `utils/roman.py` and `utils/_roman_numeral.py` and declare a dependency on [roman](https://pypi.org/project/roman/) instead.
(Lowercase roman to int support was added in the [upstream repo commit ffc86c4](https://github.com/zopefoundation/roman/commit/ffc86c43cb58438a37b9f5791669c35b17902957) Oct 1, 2024, so we would need to work around this until a roman.py release with this fix is available.


---

Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/feature-requests/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/feature-requests/options.  Or, if this is a mailing list, you can unsubscribe from the mailing list.

- **status**: pending-remind --> open-fixed
- **Comment**:

[r9974] wraps calls to `locale.setlocale()` in a try/except clause and reports a warning instead of failing when ther are problems in the locale setup.



---

**[bugs:#495] locale.Error: unsupported locale setting**

**Status:** open-fixed
**Created:** Tue Oct 08, 2024 11:34 AM UTC by Artur Stępniak
**Last Updated:** Tue Oct 15, 2024 06:34 PM UTC
**Owner:** nobody


I'm getting "locale.Error: unsupported locale setting" when running e.g. rst2man docs/man/openvpn3-log.1.rst  | groff -Tutf8 -man

Full output:
~~~
Traceback (most recent call last):
  File "/usr/bin/rst2man", line 8, in <module>
    sys.exit(rst2man())
             ^^^^^^^^^
  File "/usr/lib/python3.12/site-packages/docutils/core.py", line 760, in rst2man
    rst2something('manpage', 'Unix manual (troff)', 'user/manpage.html')
  File "/usr/lib/python3.12/site-packages/docutils/core.py", line 739, in rst2something
    locale.setlocale(locale.LC_ALL, '')
  File "/usr/lib/python3.12/locale.py", line 615, in setlocale
    return _setlocale(category, locale)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
locale.Error: unsupported locale setting
~~~

my locale setting:
~~~
locale
locale: Cannot set LC_CTYPE to default locale: No such file or directory
locale: Cannot set LC_MESSAGES to default locale: No such file or directory
locale: Cannot set LC_ALL to default locale: No such file or directory
LANG=szl_PL.UTF-8
LC_CTYPE="szl_PL.UTF-8"
LC_NUMERIC=pl_PL.UTF-8
LC_TIME=pl_PL.UTF-8
LC_COLLATE="szl_PL.UTF-8"
LC_MONETARY=pl_PL.UTF-8
LC_MESSAGES="szl_PL.UTF-8"
LC_PAPER=pl_PL.UTF-8
LC_NAME=pl_PL.UTF-8
LC_ADDRESS=pl_PL.UTF-8
LC_TELEPHONE=pl_PL.UTF-8
LC_MEASUREMENT=pl_PL.UTF-8
LC_IDENTIFICATION=pl_PL.UTF-8
LC_ALL=
~~~


---

Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/bugs/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/bugs/options.  Or, if this is a mailing list, you can unsubscribe from the mailing list.

Dear Marcello,

On 2024-10-23, Marcello Perathoner wrote:
> There is a bug in function nodes.get_language_code. It is supposed to 
> recursively call itself, but it calls another function instead. The 
> failure is masked by an overly general try...except block.

Thank you for the report. The bug is fixed in commit [r9970].

Günter

There is a bug in function nodes.get_language_code. It is supposed to 
recursively call itself, but it calls another function instead. The 
failure is masked by an overly general try...except block.

https://github.com/docutils/docutils/blob/ceb8eb76a21da5553017bedb9eca8bb18ebde57f/docutils/docutils/nodes.py#L836


mfg

--
Marcello Perathoner
mar...@pe...

To be or not to be == True

- **status**: open --> closed-fixed
- **Comment**:

Patches are commited in	[r9956].



---

**[patches:#212] Simplify type hints for readers, parsers, writers modules.**

**Status:** closed-fixed
**Group:** None
**Created:** Fri Oct 04, 2024 10:50 AM UTC by Günter Milde
**Last Updated:** Fri Oct 04, 2024 12:20 PM UTC
**Owner:** nobody
**Attachments:**

- [0001-Trim-down-overhead-of-type-hints.patch](https://sourceforge.net/p/docutils/patches/212/attachment/0001-Trim-down-overhead-of-type-hints.patch) (12.6 kB; text/x-patch)


Commits [r9872], [r9873], and [r9874] added type hints for the
"readers", "parsers", and "writers" modules increasing their size by
42, 70, and 112 lines respectively.


The reason is the provision of the exact output value for a set of specific
input vales via the `@overload` decorator for the auxiliary functions
`get_*_class()`.

IMO, this is an overkill: the `@overload` is fine, if different types of
input values result in different types of output values 
but not for individual values of the same type that return a class that is
a subclass of a well defined abstract base class (readers.Reader,
parsers.Parser, writers.Writer) and where the set of admissible values is
not known (any 3rd party component is found, too).

My argument is, that the `get_*_class()` function is intended for use
when the component class is fetched at runtime from user configuration
(which means we only know that the return value conforms to the interface
of the abstract base class).

In cases where a statical type checker knows the `reader_name`,
`parser_name`, `writer_name` (and this matters) there is no need to use
`get_*_class()` but the calling code may directly import the component
class.

Unless there is a convincing use case, I suggest the attached patch to reverse  the changes to
the `get_*_class()` functions.





---

Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/patches/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/patches/options.  Or, if this is a mailing list, you can unsubscribe from the mailing list.

- **status**: open --> open-fixed
- **Comment**:

The patch is committed in [r9953].



---

**[bugs:#494] rst2odt: TypeError with --stylesheet=styles.xml**

**Status:** open-fixed
**Labels:** ODT Writer 
**Created:** Fri Oct 04, 2024 10:52 AM UTC by Paul Kishimoto
**Last Updated:** Tue Oct 15, 2024 06:36 PM UTC
**Owner:** nobody


The documentation (page “ODT Writer for Docutils”, section [“4 Styles and Classes”](https://docutils.sourceforge.io/docs/user/odt.html#styles-and-classes)) states:
> Note that with the `--stylesheet` command line option, you can use either `styles.odt` or `styles.xml`, as described below. Use of `styles.odt` is recommended over `styles.xml`.

With Python 3.12.3 and docutils 0.21.2, it appears that styles.xml is not usable, either from the command line or programmatically.

To reproduce from the command line:
1. A file `empty.rst`.
2. A file `styles.xml`, extracted from any valid ODT archive.
3. Run `$ docutils --writer=odt --stylesheet=styles.xml --traceback empty.rst >bug.odt`

The output is:
```
Traceback (most recent call last):
  File "/home/khaeru/.venv/3.12/bin/docutils", line 8, in <module>
    sys.exit(main())
             ^^^^^^
  File "/home/khaeru/.venv/3.12/lib/python3.12/site-packages/docutils/__main__.py", line 78, in main
    publish_cmdline(reader_name=args.reader,
  File "/home/khaeru/.venv/3.12/lib/python3.12/site-packages/docutils/core.py", line 402, in publish_cmdline
    output = publisher.publish(
             ^^^^^^^^^^^^^^^^^^
  File "/home/khaeru/.venv/3.12/lib/python3.12/site-packages/docutils/core.py", line 237, in publish
    output = self.writer.write(self.document, self.destination)
             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/khaeru/.venv/3.12/lib/python3.12/site-packages/docutils/writers/__init__.py", line 80, in write
    self.translate()
  File "/home/khaeru/.venv/3.12/lib/python3.12/site-packages/docutils/writers/odf_odt/__init__.py", line 510, in translate
    self.visitor.retrieve_styles(self.EXTENSION)
  File "/home/khaeru/.venv/3.12/lib/python3.12/site-packages/docutils/writers/odf_odt/__init__.py", line 941, in retrieve_styles
    self.dom_stylesheetcontent = etree.fromstring(
                                 ^^^^^^^^^^^^^^^^^
  File "/usr/lib/python3.12/xml/etree/ElementTree.py", line 1335, in XML
    parser.feed(text)
TypeError: a bytes-like object is required, not 'NoneType'
```

The same error occurs when calling:
```python
from docutils.core import publish_string

publish_string(
    source="",
    writer_name="odt",
    settings_overrides={"stylesheet": "styles.xml"},
)
```

This seems to be a consequence of `ODFTranslator.retrieve_styles()` ([here](https://sourceforge.net/p/docutils/code/HEAD/tree/trunk/docutils/docutils/writers/odf_odt/__init__.py#l925)), wherein:

1. `s2 = None` is set.
2. If the provided path has extension `extension` (e.g. ".odt"), it is overwritten with content read from `content.xml` in the archive; **but** if the provided path has extension ".xml", it remains `None`.
3. This value is assigned to `self.str_stylesheetcontent` and then parsed with `etree.tostring()`.

Also, the parsed `self.dom_stylesheetcontent` does not appear to be used anywhere else in the module. It's not clear why it is needed.


---

Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/bugs/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/bugs/options.  Or, if this is a mailing list, you can unsubscribe from the mailing list.

On 2024-10-20, engelbert gruber wrote:


>> 3. what if there is no alt-text ? 

Filename + warning