docutils-develop — For developer discussions of the implementation.

[Docutils-develop] [docutils:bugs] #468 New release of libpaper (paperconf) breark rst2odt

[Günter M. <mi...@us...>]

Thank you for the report and suggestion.
One problem is, that the "old" `paperconf` command does not recognize the `--unit` option.
Maybe we can try the old syntax and processing if the new command fails before falling back to
"letter" or "A4".


---

** [bugs:#468] New release of libpaper (paperconf) breark rst2odt**

**Status:** open
**Created:** Wed Mar 08, 2023 10:59 AM UTC by fouinix
**Last Updated:** Mon Mar 13, 2023 03:52 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.

[Docutils-develop] [docutils:bugs] #469 update license metadata on pypi

[Adam T. <aa-...@us...>]

- **status**: open --> closed-invalid



---

** [bugs:#469] update license metadata on pypi**

**Status:** closed-invalid
**Labels:** license 
**Created:** Wed Mar 29, 2023 08:44 PM UTC by pierrick rambaud
**Last Updated:** Thu Mar 30, 2023 09:52 PM UTC
**Owner:** nobody


I followed recently a presentation on FOSS licensing and I wanted to make sure that my projects were not hiding some Licensing incompatibilities. Some automated softawres have been proposed an I decided to go with https://github.com/FHPythonUtils/LicenseCheck. 

It reads the pypi license metadata of every one of your dependencies and set a table with compatibility issues. Docutils is raising issues with everyone as the license is not specified in pypi in a readable way. 

Would it be possible to update the license written there to make it machine reading compatible ? 
I wanted to make a proposal myself but I realized afterward that this (https://github.com/docutils/docutils) is just a mirror.


---

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.

[Docutils-develop] [docutils:bugs] #469 update license metadata on pypi

[Adam T. <aa-...@us...>]

Hi,

Please raise an issue with that project to use PyPI trove classifiers, Docutils sets these correctly in our metadata ( https://pypi.org/project/docutils/ )

Thanks,
Adam


---

** [bugs:#469] update license metadata on pypi**

**Status:** open
**Labels:** license 
**Created:** Wed Mar 29, 2023 08:44 PM UTC by pierrick rambaud
**Last Updated:** Wed Mar 29, 2023 08:44 PM UTC
**Owner:** nobody


I followed recently a presentation on FOSS licensing and I wanted to make sure that my projects were not hiding some Licensing incompatibilities. Some automated softawres have been proposed an I decided to go with https://github.com/FHPythonUtils/LicenseCheck. 

It reads the pypi license metadata of every one of your dependencies and set a table with compatibility issues. Docutils is raising issues with everyone as the license is not specified in pypi in a readable way. 

Would it be possible to update the license written there to make it machine reading compatible ? 
I wanted to make a proposal myself but I realized afterward that this (https://github.com/docutils/docutils) is just a mirror.


---

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.

Re: [Docutils-develop] Release 0.20

[Adam T. <aat...@ou...>]

Dear Günter, Docutils developers,

Sorry for such a long delay in responding!

[snip]

> YES, it is time for a new release.

Great!

[snip]

> Before the actual release, we should decide on the way ahead and update the
> announcments of future changes
> https://docutils.sourceforge.io/RELEASE-NOTES.html#future-changes

> front end tools:
>   - Which Docutils version will drop the ``.py`` extension?
> 
>   - Keep/drop less often required ``rst2*`` tools? Which?
> 
>   - announce switch of packaging framework
> 
>   see also https://sourceforge.net/p/docutils/patches/186/
>  
>   Proposal [GM]:
>     - implement in 0.21
>     - keep [rst2html, rst2html4, rst2html5, rst2latex, rst2man,
>             rst2odt, rst2pseudoxml, rst2s5, rst2xetex, rst2xml]

I agree with your proposal: drop in 0.21. I would suggest only keeping
rst2html, rst2html5, rst2latex, rst2man, rst2odt, rst2pseudoxml, and rst2xml,
but this can always be discussed later and should not futher delay the 0.20
release.


> input encoding:
>   - Announce new default "utf-8"?
>     For which Docutils version?
> 
>   - Which Docutils version shall implement the already announced changes?
>     (They are rather a bugfix, make the code simpler, a patch is ready.)
> 
>   see also https://sourceforge.net/p/docutils/patches/194/
>  
>   Proposal [GM]:
>     implement already announced changes in 0.21
>     announce "utf-8" as default for 1.0
>     announce removal of encoding detection for 2.0

I agree with all three of your proposals here.

> install.py
>   - Remove in which Docutils version?
>     (The removal is already announced but without affected version.)
>    
>   Proposal [GM]:
>     Remove in 0.21, announce this now.

Agree to remove in 0.21, announce in 0.20.

 
> * Drop support for older Python versions? (Which?, When?)
> 
>   Typing hints become a lot simpler (e.g. with the "|" operator) in 3.10.0
>  
>   Proposal [GM]
>     Raise requirement to >=3.9 in 0.21, announce now.
>     (This is the default Python3 version in current Debian/stable,
>     the most "conservative" major Linux release.)

Agree to require 3.9 in 0.21, announce in 0.20.

For interest, Sphinx has a policy__ to support:
"all minor versions of Python released in the past 42 months from the ...
release date with a minimum of 3 minor versions of Python"

__ https://www.sphinx-doc.org/en/master/internals/release-process.html#python-version-support-policy


>> * Future of ``core.publish_string()`` API function:
>> 
>>   a) Keep current behaviour ::
>>  
>>       def publish_string(source: Union[bytes, str],
>>                          [...]
>>                          enable_exit_status=False) -> Union[bytes, str]
>>              
>>      as "wart", just improve documentation?
>>              
>>   b) Deprecate ``publish_string()`` and provide new ``publish_str()``
>>      and ``publish_bytes()`` functions?
>>  
>>   c) Return a sub-class of ``str`` with ``__bytes__()`` method that
>>      encodes with ``encoding`` and ``encoding_errors`` set to the
>>      "output_encoding" and "output_encoding_errors" setting values?
>>     
>>      - as "subtly" changed behaviour, or
>>      - with a new function replacing ``publish_string()``
>>        (find a good name!)?
>> 
>>   Proposal [GM]
>>     - explore c)
>>     - remove ``core.publish_bytes()`` before releasing 0.20.

> I prepared a patch for option c) with a new function attribute 'auto_encode
> for `core.publish_string()`. This would allow to keep the name and switch to
> a behaviour matching it (returning a string, not bytes) gradually (by 
> switching the default value and eventually removing the option later). See below.

I am content to go with option (c), but I would want to simultaneously announce
the version where the default would change to ``auto_encode=False`` and the
version where ``publish_string()`` would only support returning ``str``
instances.

I think that it might be possible to implement the new ``auto_encode``
parameter without a custom ``str`` subclass, but unfortunatley I won't have
time until May to properly work on such an implementation.

Otherwise I would support option (b) to add a new ``publish_str()``. I think we
should keep the ``publish_bytes()`` function in either case. 

>> Are there other open issues that should be adressed before the next release?

> * Implement the patch for a configurable include_root?
>   https://sourceforge.net/p/docutils/feature-requests/91/

I think the ``include_root`` change (and others) can be delayed, they are not
requirements for 0.20

Thanks,
Adam

[Docutils-develop] [docutils:bugs] #465 RST parser is inconsistent about adding line numbers to nodes

[Günter M. <mi...@us...>]

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

This is a duplicate of https://sourceforge.net/p/docutils/feature-requests/41/



---

** [bugs:#465] RST parser is inconsistent about adding line numbers to nodes**

**Status:** closed-duplicate
**Created:** Mon Jan 23, 2023 07:37 PM UTC by Hood Chatham
**Last Updated:** Mon Jan 23, 2023 07:38 PM UTC
**Owner:** nobody


The rst parser fills in line numbers for most nodes. But some types of nodes like definition_list, enum_list, and admonitions don't get line numbers. All nodes should get line numbers.

As far as I can tell there is no test coverage for the `line` field.


---

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.

Re: [Docutils-develop] Release 0.20

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

Dear Docutils developers,

an update and request for comments...

On 2023-01-10, Guenter Milde via Docutils-develop wrote:
...
> it is time for a new release.

...

> * Future of ``core.publish_string()`` API function:

>   a) Keep current behaviour ::

>       def publish_string(source: Union[bytes, str], 
>                          [...]
>                          enable_exit_status=False) -> Union[bytes, str]

>      as "wart", just improve documentation?

>   b) Deprecate ``publish_string()`` and provide new ``publish_str()`` 
>      and ``publish_bytes()`` functions?

>   c) Return a sub-class of ``str`` with ``__bytes__()`` method that
>      encodes with ``encoding`` and ``encoding_errors`` set to the
>      "output_encoding" and "output_encoding_errors" setting values?

>      - as "subtly" changed behaviour, or
>      - with a new function replacing ``publish_string()``
>        (find a good name!)?

>   Proposal [GM]
>     - explore c)
>     - remove ``core.publish_bytes()`` before releasing 0.20.

I prepared a patch for option c) with a new function attribute
'auto_encode' for `core.publish_string()`. This would allow to
keep the name and switch to a behaviour matching it (returning a string, not
bytes) gradually (by switching the default value and eventually removing the
option later). See below.

> Are there other open issues that should be adressed before the next release?

* Implement the patch for a configurable include_root?
  https://sourceforge.net/p/docutils/feature-requests/91/

Thanks,
Günter


Subject: [PATCH] Define and use new `str` sub-class for string output.

New class `io.OutString` adds "encoding" and "errors" attributes
to `str`.

Use it for `io.StringOutput`. Allows storing the "output_encoding"
and "output_encoding_error_handler" settings in a transparent
and easy to process way.

Add "auto_encode" argument to publish_string() and
publish_programatically() to give the user an option to select the
output type (`bytes` or `str`) in a way that does not interfere with the
intended encoding of the output.
---
 docutils/docutils/core.py       | 34 ++++++-------
 docutils/docutils/io.py         | 84 +++++++++++++++++++++++++++++++--
 docutils/test/test_io.py        | 59 +++++++++++++++++++++++
 docutils/test/test_publisher.py | 21 ++++++++-
 4 files changed, 177 insertions(+), 21 deletions(-)

diff --git a/docutils/docutils/core.py b/docutils/docutils/core.py
index 03c60279f..5d4793f5d 100644
--- a/docutils/docutils/core.py
+++ b/docutils/docutils/core.py
@@ -427,26 +427,21 @@ def publish_string(source, source_path=None, destination_path=None,
                    writer=None, writer_name='pseudoxml',
                    settings=None, settings_spec=None,
                    settings_overrides=None, config_section=None,
-                   enable_exit_status=False):
+                   enable_exit_status=False,
+                   auto_encode=True):
     """
     Set up & run a `Publisher` for programmatic use with string I/O.
 
     Accepts a `bytes` or `str` instance as `source`.
-    The output is encoded according to the "output_encoding" setting;
-    the return value is a `bytes` instance (unless `output_encoding`_
-    is "unicode", see below).
 
-    To get Docutils output as `str` instance, use `publish_parts()`::
+    If `auto_encode` is True, the output is encoded according to the
+    `output_encoding`_ setting; the return value is a `bytes` instance
+    (unless `output_encoding`_ is "unicode",
+    cf. `docutils.io.StringOutput.write()`).
 
-      output = publish_parts(...)['whole']
-
-    or set `output_encoding`_ to the pseudo encoding name "unicode", e.g.::
-
-      publish_string(..., settings_overrides={'output_encoding': 'unicode'})
-
-    Beware that the `output_encoding`_ setting may affect the content
-    of the output (e.g. an encoding declaration in HTML or XML or the
-    representation of characters as LaTeX macro vs. literal character).
+    If `auto_encode` is False, the output is an instance of a `str`
+    sub-class with "output_encoding" and "output_encoding_error_handler"
+    settings stored as `encoding` and `errors` attributes.
 
     Parameters: see `publish_programmatically()`.
 
@@ -463,7 +458,8 @@ def publish_string(source, source_path=None, destination_path=None,
         settings=settings, settings_spec=settings_spec,
         settings_overrides=settings_overrides,
         config_section=config_section,
-        enable_exit_status=enable_exit_status)
+        enable_exit_status=enable_exit_status,
+        auto_encode=auto_encode)
     return output
 
 
@@ -617,7 +613,8 @@ def publish_programmatically(source_class, source, source_path,
                              writer, writer_name,
                              settings, settings_spec,
                              settings_overrides, config_section,
-                             enable_exit_status):
+                             enable_exit_status,
+                             auto_encode=True):
     """
     Set up & run a `Publisher` for custom programmatic use.
 
@@ -709,6 +706,9 @@ def publish_programmatically(source_class, source, source_path,
       defined by `settings_spec`.  Used only if no `settings` specified.
 
     * `enable_exit_status`: Boolean; enable exit status at end of processing?
+
+    * `auto_encode`: Boolean; encode string output and return `bytes`?
+      Ignored with `io.FileOutput`.
     """
     publisher = Publisher(reader, parser, writer, settings=settings,
                           source_class=source_class,
@@ -718,5 +718,7 @@ def publish_programmatically(source_class, source, source_path,
         settings_spec, settings_overrides, config_section)
     publisher.set_source(source, source_path)
     publisher.set_destination(destination, destination_path)
+    if not auto_encode and isinstance(publisher.destination, io.StringOutput):
+        publisher.destination.auto_encode = auto_encode
     output = publisher.publish(enable_exit_status=enable_exit_status)
     return output, publisher
diff --git a/docutils/docutils/io.py b/docutils/docutils/io.py
index 2007a5cef..2162db2b3 100644
--- a/docutils/docutils/io.py
+++ b/docutils/docutils/io.py
@@ -74,6 +74,57 @@ def error_string(err):
     return f'{err.__class__.__name__}: {err}'
 
 
+class OutString(str):
+    """Return a string representation of `object` with known encoding.
+
+    Differences to `str()`:
+
+    If the `encoding` is given, both `str` instances and byte-like objects
+    are stored as text string, the latter decoded with `encoding` and
+    `errors` (defaulting to 'strict').
+
+    The encoding is never guessed. If `encoding` is None (the default),
+    an informal string representation is used, also if `errors` are given.
+
+    The original or intended encoding and error handler are stored in the
+    attributes `encoding` and `errors`.
+    Typecasting to `bytes` uses the stored values.
+    """
+
+    def __new__(cls, object, encoding=None, errors='strict'):
+        """Return a new OutString object.
+
+        Provisional.
+        """
+        try:
+            # decode bytes-like objects if encoding is known
+            return super().__new__(cls, object, encoding, errors)
+        except TypeError:
+            return super().__new__(cls, object)
+
+    def __init__(self, object, encoding=None, errors='strict'):
+        """Set "encoding" and "errors" attributes."""
+        self.encoding = encoding
+        self.errors = errors
+
+    def __bytes__(self):
+        try:
+            return super().encode(self.encoding, self.errors)
+        except TypeError:
+            raise TypeError('OutString instance without known encoding')
+
+    def __repr__(self):
+        if self.errors != 'strict':
+            errors_arg = f', errors={self.errors!r}'
+        else:
+            errors_arg = ''
+        return (f'{self.__class__.__name__}({super().__repr__()}, '
+                f'encoding={self.encoding!r}{errors_arg})')
+
+    def encode(self, encoding=None, errors=None):
+        return super().encode(encoding or self.encoding, errors or self.errors)
+
+
 class Input(TransformSpec):
     """
     Abstract base class for input wrappers.
@@ -264,14 +315,14 @@ class Output(TransformSpec):
         raise NotImplementedError
 
     def encode(self, data):
-        """Encode and return `data`.
+        """
+        Encode and return `data`.
 
         If `data` is a `bytes` instance, it is returned unchanged.
         Otherwise it is encoded with `self.encoding`.
 
         If `self.encoding` is set to the pseudo encoding name "unicode",
         `data` must be a `str` instance and is returned unchanged.
-
         """
         if self.encoding and self.encoding.lower() == 'unicode':
             assert isinstance(data, str), ('output encoding is "unicode" '
@@ -596,14 +647,39 @@ class StringOutput(Output):
 
     default_destination_path = '<string>'
 
+    def __init__(self, destination=None, destination_path=None,
+                 encoding=None, error_handler='strict', auto_encode=True):
+        self.auto_encode = auto_encode
+        """Let `write()` encode the output document and return `bytes`."""
+        super().__init__(destination, destination_path,
+                         encoding, error_handler)
+
     def write(self, data):
-        """Encode `data`, store it in `self.destination`, and return it.
+        """Store `data` in `self.destination`, and return it.
 
+        If `self.auto_encode` is False, store and return a `str`
+        sub-class instance with "encoding" and "errors" attributes
+        set to `self.encoding` and `self.error_handler`.
+
+        If `self.auto_encode` is True, encode `data` with `self.encoding`
+        and `self.error_handler` and store/return a `bytes` instance.
+        Exception:
         If `self.encoding` is set to the pseudo encoding name "unicode",
         `data` must be a `str` instance and is returned unchanged
         (cf. `Output.encode`).
+        Beware that the `output_encoding`_ setting may affect the content
+        of the output (e.g. an encoding declaration in HTML or XML or the
+        representation of characters as LaTeX macro vs. literal character).
         """
-        self.destination = self.encode(data)
+        if self.auto_encode:
+            self.destination = self.encode(data)
+            return self.destination
+
+        if not self.encoding or self.encoding.lower() == 'unicode':
+            encoding = None
+        else:
+            encoding = self.encoding
+        self.destination = OutString(data, encoding, self.error_handler)
         return self.destination
 
 
diff --git a/docutils/test/test_io.py b/docutils/test/test_io.py
index 17b77eaa1..a1485ce0a 100755
--- a/docutils/test/test_io.py
+++ b/docutils/test/test_io.py
@@ -189,6 +189,19 @@ class OutputTests(unittest.TestCase):
         fo.write(self.udata)
         self.assertEqual(self.udrain.getvalue(), self.udata)
 
+    def test_write_auto_encode_false(self):
+        so = io.StringOutput(encoding='latin1', error_handler='replace',
+                             auto_encode=False)
+        output = so.write(self.udata)
+        # store output in self.destination and also return it
+        self.assertEqual(output, self.udata)
+        self.assertEqual(so.destination, self.udata)
+        # store also encoding and encoding error handler ...
+        self.assertEqual(output.encoding, 'latin1')
+        self.assertEqual(output.errors, 'replace')
+        # ... to allow easy conversion to `bytes`:
+        self.assertEqual(bytes(output), self.bdata)
+
     def test_FileOutput_hande_io_errors_deprection_warning(self):
         with self.assertWarnsRegex(DeprecationWarning,
                                    '"handle_io_errors" is ignored'):
@@ -224,6 +237,52 @@ class OutputTests(unittest.TestCase):
         self.assertRaises(ValueError, fo.write, self.udata)
 
 
+class OutStringTests(unittest.TestCase):
+
+    def test__init__defaults(self):
+        """Test `__new__()` and `__init__()` with default values."""
+
+        os = io.OutString('Grüße')
+        self.assertEqual(str(os), 'Grüße')
+        self.assertEqual(os.encoding, None)
+        self.assertEqual(os.errors, 'strict')
+        # converting to `bytes` fails if the encoding is not known:
+        with self.assertRaises(TypeError):
+            self.assertEqual(bytes(os), 'Grüße')
+        # without known encoding, `bytes` and other incompatible types
+        # are converted to their string representation ...
+        bos = io.OutString(b'gut')
+        self.assertEqual(str(bos), "b'gut'")
+        bos_e = io.OutString('Grüße'.encode('latin1'), errors='ignore')
+        self.assertEqual(str(bos_e), r"b'Gr\xfc\xdfe'")
+        bos = io.OutString(b'gut', encoding=None)
+        self.assertEqual(str(bos), "b'gut'")
+
+    def test__init__custom_attributes(self):
+        """Test `__new__()` and `__init__()` with custom encoding."""
+        os8 = io.OutString('Grüße', encoding='utf-8')
+        self.assertEqual(str(os8), 'Grüße')
+        self.assertEqual(bytes(os8), b'Gr\xc3\xbc\xc3\x9fe')
+        self.assertEqual(repr(os8), "OutString('Grüße', encoding='utf-8')")
+        # With known encoding, "bytes-like" objects are decoded
+        bos1 = io.OutString(b'Gr\xfc\xdfe', encoding='latin1')
+        self.assertEqual(str(bos1), 'Grüße')
+        self.assertEqual(bytes(bos1), b'Gr\xfc\xdfe')
+        # Invalid encodings (including the empty string) raise an error
+        with self.assertRaises(LookupError):
+            io.OutString(b'Gr\xfc\xdfe', encoding='')
+
+    def test__init__custom_errors(self):
+        """Test `__new__()` and `__init__()` with custom `errors`."""
+        ts8_r = io.OutString('Grüße', encoding='utf-8', errors='replace')
+        # Encoding uses the stored error handler:
+        self.assertEqual(ts8_r.encode('ascii'), b'Gr??e')
+        # Initialization with a `bytes` object uses the error handler, too:
+        bts8_r = io.OutString(b'Gr\xfc\xdfe', encoding='utf-8',
+                              errors='replace')
+        self.assertEqual(str(bts8_r), 'Gr��e')
+
+
 class ErrorOutputTests(unittest.TestCase):
     def test_defaults(self):
         e = io.ErrorOutput()
diff --git a/docutils/test/test_publisher.py b/docutils/test/test_publisher.py
index 6177ad6d2..a731d2434 100755
--- a/docutils/test/test_publisher.py
+++ b/docutils/test/test_publisher.py
@@ -80,7 +80,8 @@ class PublisherTests(unittest.TestCase):
                                        'nonexisting/path'],
                                  settings_overrides={'traceback': True})
 
-    def test_publish_string(self):
+    def test_publish_string_input_encoding(self):
+        """Test handling of encoded input."""
         # Transparently decode `bytes` source (with "input_encoding" setting)
         # default: auto-detect, fallback utf-8
         # Output is encoded according to "output_encoding" setting.
@@ -102,6 +103,24 @@ class PublisherTests(unittest.TestCase):
                                      settings_overrides=settings)
         self.assertTrue(output.endswith('Grüße\n'))
 
+    def test_publish_string_output_encoding(self):
+        settings = {'_disable_config': True,
+                    'datestamp': False,
+                    'output_encoding': 'latin1',
+                    'output_encoding_error_handler': 'replace'}
+        source = 'Grüß → dich'
+        expected = ('<document source="<string>">\n'
+                    '    <paragraph>\n'
+                    '        Grüß → dich\n')
+        # current default: encode output, return `bytes`
+        output = core.publish_string(source, settings_overrides=settings)
+        self.assertEqual(output, expected.encode('latin1', 'replace'))
+        # no encoding if `auto_encode` is False:
+        output = core.publish_string(source, settings_overrides=settings,
+                                     auto_encode=False)
+        self.assertEqual(output, expected)
+        # self.assertEqual(output.encoding, 'latin1')
+
 
 class PublishDoctreeTestCase(unittest.TestCase, docutils.SettingsSpec):
 
-- 
2.30.2

[Docutils-develop] [docutils:patches] #201 Adapt tests to Sphinx 6.0.0

[Günter M. <mi...@us...>]

Thank you for the patch.
I suppose you speak about "Pygments" (not Sphinx).  
Sphinx is not required by Docutils so the tests should be independent of the Sphinx version.

For Pygments (which is used, if installed, without version restrictions), the tests should pass with any Pygments version (either adapting or skipping test cases that are known to fail).
As such, the patch may fix the tests for some installations and break them for others.



---

** [patches:#201] Adapt tests to Sphinx 6.0.0**

**Status:** open
**Group:** None
**Created:** Wed Jan 04, 2023 03:51 PM UTC by Daniel Garcia Moreno
**Last Updated:** Wed Jan 04, 2023 03:51 PM UTC
**Owner:** nobody
**Attachments:**

- [sphinx-6.0.0.patch](https://sourceforge.net/p/docutils/patches/201/attachment/sphinx-6.0.0.patch) (5.8 kB; text/x-patch)


Sphinx 6.0.0 changes the format a bit, this patch fixes some tests that are broken with the latest release.


---

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.

[Docutils-develop] [docutils:bugs] #464 Remove use of deprecated locale.getdefaultlocale

[Günter M. <mi...@us...>]

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

Fixed in [r9314]. Thank you for the report.



---

** [bugs:#464] Remove use of deprecated locale.getdefaultlocale**

**Status:** open-fixed
**Created:** Mon Dec 19, 2022 09:11 PM UTC by Matthias Koeppe
**Last Updated:** Mon Dec 19, 2022 09:11 PM UTC
**Owner:** nobody


docutils.io calls the function locale.getdefaultlocale, which is deprecated since Python 3.11 - https://docs.python.org/3/library/locale.html#locale.getdefaultlocale, 

Reference: https://trac.sagemath.org/ticket/33842#comment:116


---

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.

[Docutils-develop] Release 0.20 (was: Request for a patch release 0.19.1)

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

Dear Docutils developers,

a happy new year to everyone!

On 2023-01-07, engelbert gruber wrote:
> On 7 Jan 2023 Matthias Geier <mat...@gm...> wrote:

>> A few months ago, I've reported a problem with sphinxcontrib-bibtex
...
>> The maintainer of sphinxcontrib-bibtex has kindly provided a patch
>> (https://sourceforge.net/p/docutils/patches/195/), which has already
>> been merged in the meantime.

>> I don't know the release procedure nor the roadmap of docutils, but
>> would it be possible to create a new docutils release that contains
>> this fix (and maybe other improvements)?
...

All in all, we have fixed 4 bugs and merged 2 patches since the 
last release (see for tags "open-fixed" or "open-accepted" in
https://sourceforge.net/p/docutils/_list/tickets) so YES, 
it is time for a new release.

The long list of changes and improvements (see HISTORY.txt) indicates
that this is not a pure bug-fix release, so (following our policies), the
version number will be 0.20.

Before the actual release, we should decide on the way ahead and update the
announcments of future changes
https://docutils.sourceforge.io/RELEASE-NOTES.html#future-changes

front end tools:
  - Which Docutils version will drop the ``.py`` extension?

  - Keep/drop less often required ``rst2*`` tools? Which?

  - announce switch of packaging framework

  see also https://sourceforge.net/p/docutils/patches/186/
  
  Proposal [GM]: 
    - implement in 0.21
    - keep [rst2html, rst2html4, rst2html5, rst2latex, rst2man, 
            rst2odt, rst2pseudoxml, rst2s5, rst2xetex, rst2xml]

input encoding:
  - Announce new default "utf-8"?
    For which Docutils version?

  - Which Docutils version shall implement the already announced changes?
    (They are rather a bugfix, make the code simpler, a patch is ready.)

  see also https://sourceforge.net/p/docutils/patches/194/
  
  Proposal [GM]:
    implement already announced changes in 0.21
    announce "utf-8" as default for 1.0
    announce removal of encoding detection for 2.0

install.py
  - Remove in which Docutils version?
    (The removal is already announced but without affected version.)
    
  Proposal [GM]:
    Remove in 0.21, announce this now.


Further decisions:    

* Can we agree on the Docutils command-line usage pattern change? ::

    - <toolname> [options] [<source> [<destination>]]
    + <toolname> [options] source [source2 [source3 [...]]]

  For the rationale, see https://clig.dev/#arguments-and-flags
  and https://sourceforge.net/p/docutils/feature-requests/36/ 
  
  If yes, announce now (documentation patch is ready).
  
  Proposal [GM]:
    Yes
  
* Drop support for older Python versions? (Which?, When?)

  Typing hints become a lot simpler (e.g. with the "|" operator) in 3.10.
  
  Proposal [GM]
    Raise requirement to >=3.9 in 0.21, announce now.
    (This is the default Python3 version in current Debian/stable,
    the most "conservative" major Linux release.)

* Future of ``core.publish_string()`` API function:

  a) Keep current behaviour ::
  
      def publish_string(source: Union[bytes, str], 
                         [...]
                         enable_exit_status=False) -> Union[bytes, str]
              
     as "wart", just improve documentation?
              
  b) Deprecate ``publish_string()`` and provide new ``publish_str()`` 
     and ``publish_bytes()`` functions?
  
  c) Return a sub-class of ``str`` with ``__bytes__()`` method that
     encodes with ``encoding`` and ``encoding_errors`` set to the
     "output_encoding" and "output_encoding_errors" setting values?
     
     - as "subtly" changed behaviour, or
     - with a new function replacing ``publish_string()``
       (find a good name!)?

  Proposal [GM]
    - explore c)
    - remove ``core.publish_bytes()`` before releasing 0.20.
    
  
Are there other open issues that should be adressed before the next release?


Thanks,
Günter

Re: [Docutils-develop] [Docutils-users] Request for a patch release 0.19.1

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

develop list would be the correct destination ....


On Sat, 7 Jan 2023 at 12:21, Matthias Geier <mat...@gm...>
wrote:

> Dear docutils maintainers.
>
> A few months ago, I've reported a problem with sphinxcontrib-bibtex
> (https://github.com/mcmtroffaes/sphinxcontrib-bibtex/issues/309),
> which turned out to actually be a problem with docutils.
> There is also a related Sphinx issue
> (https://github.com/sphinx-doc/sphinx/issues/10784) which shows that
> the problem can also appear without using sphinxcontrib-bibtex.
>
> The maintainer of sphinxcontrib-bibtex has kindly provided a patch
> (https://sourceforge.net/p/docutils/patches/195/), which has already
> been merged in the meantime.
>
> I don't know the release procedure nor the roadmap of docutils, but
> would it be possible to create a new docutils release that contains
> this fix (and maybe other improvements)?
>
> Thanks in advance!
>
> In case you are wondering how the problem looks in practice, here is
> an example:
> https://nbsphinx.readthedocs.io/en/0.8.11/a-normal-rst-file.html#citations
>
> cheers,
> Matthias
>
>
> _______________________________________________
> Docutils-users mailing list
> Doc...@li...
> https://lists.sourceforge.net/lists/listinfo/docutils-users
>
> Please use "Reply All" to reply to the list.
>

[Docutils-develop] [docutils:bugs] #384 allow omission of citations (rst2latex with --use-bibtex option)

[Günter M. <mi...@us...>]

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

Fixed in [r9312].
Support for the "use-bibtex" option is provisional: the option may be renamed, removed or changed without advance warning!

Considerations: also support "use-biblatex"?
Long-term: a `bibliography::` or `.. citations::` directive.



---

** [bugs:#384] allow omission of citations (rst2latex with --use-bibtex option)**

**Status:** open-fixed
**Labels:** rst2latex 
**Created:** Fri Dec 20, 2019 07:11 PM UTC by Alan
**Last Updated:** Tue Mar 03, 2020 09:41 PM UTC
**Owner:** nobody


Using the incredibly helpful `--use-bibtex=mybst,mybib` option, unless I provide targets for all the citation references, I do not get citation references in the text.  Instead the citation references marked as errors. Since I provide the citation info in ``mybib``, this seems completely pointless; can it be turned off?

Günter asked that I file this as a bug report.


---

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.

[Docutils-develop] [docutils:bugs] #460 default settings do not provide required settings values

[Günter M. <mi...@us...>]

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

Closing this bug as it is rather a misunderstanding than wrong behaviour.
Suggestions for improving the documentation are still welcome.



---

** [bugs:#460] default settings do not provide required settings values**

**Status:** closed-invalid
**Labels:** standalone reader 
**Created:** Sat Nov 12, 2022 02:17 AM UTC by Ryan de Kleer
**Last Updated:** Wed Nov 30, 2022 09:24 PM UTC
**Owner:** nobody


# Platform
Windows 10
Python 3.7
docutils 0.19.1b.dev

# Issue
Generating a document with the standalone reader fails with default settings.

# Example
```python
from docutils.readers import standalone
from docutils.parsers import rst
from docutils import io
from docutils.frontend import get_default_settings

from docutils import __version__

rst_src = """
A Document
----------
Simple but enough.
"""

def try_this():
    print(__version__)

    src = io.StringInput(rst_src)
    parser = rst.Parser()
    reader = standalone.Reader(parser=parser)
    settings = get_default_settings(reader)
    document = reader.read(src, parser, settings)
    
 try_this()
```

Results in:

```python
0.19.1b.dev
Traceback (most recent call last):
 line 19, in try_this
    document = reader.read(src, parser, settings)
 
 ...
 
File "docutils/parsers/rst/states.py", line 607, in init_customizations
    if settings.pep_references:
AttributeError: 'Values' object has no attribute 'pep_references'
```




---

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.

[Docutils-develop] [docutils:bugs] #463 Bug in nodes.py warnings

[Günter M. <mi...@us...>]

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

Fixed in [r9310]. Thank you for the report and sorry for the breaks.

As a future-proof workaround, you may consider heading the tip in the DeprecationMessage
and set the class name directly instead of via the deprecated node.set_class() method.



---

** [bugs:#463] Bug in nodes.py warnings**

**Status:** open-fixed
**Created:** Thu Dec 08, 2022 01:41 PM UTC by Julianus Pfeuffer
**Last Updated:** Thu Dec 08, 2022 01:41 PM UTC
**Owner:** nobody


Hi!

I think https://sourceforge.net/p/docutils/code/8949/
introduced a bug in https://sourceforge.net/p/docutils/code/HEAD/tree/trunk/docutils/docutils/nodes.py#l1071
Not sure if you can split the string with a comma there.

It breaks a lot of code.
The error is:

~~~
Exception occurred:
  File "/opt/hostedtoolcache/Python/3.11.0/x64/lib/python3.11/site-packages/docutils/nodes.py", line 1069, in set_class
    warnings.warn('docutils.nodes.Element.set_class() is deprecated; '
TypeError: argument for warn() given by name ('stacklevel') and position (3)
~~~


---

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.

[Docutils-develop] Proposal: Documentation policy change on Unicode use

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

Dear Docutils developers,

an update: while we are at it, I propose to allow literal Unicode in both,
documentation and source code (except for identifiers).

If there is no objection or alternative, I would commit the patch below
in a months time.

.. include:: <isolat1.txt>

G|uuml|nter


>From 5eb431cc0a4fd3f4f5c1581f9ca74653768b020e Mon Sep 17 00:00:00 2001
From: milde <mi...@us...>
Date: Mon, 28 Nov 2022 22:22:17 +0100
Subject: [PATCH] Policy change: accept literal Unicode characters except for
 identifiers.

With UTF-8 as default encoding for Python source code and widespread
Unicode support in todays editors on all platforms,
there is no need to be more restrictive than PEP 8 any more.
---
 docutils/docs/dev/policies.txt | 14 +++++---------
 1 file changed, 5 insertions(+), 9 deletions(-)

diff --git a/docutils/docs/dev/policies.txt b/docutils/docs/dev/policies.txt
index f46c143d2..e95c33389 100644
--- a/docutils/docs/dev/policies.txt
+++ b/docutils/docs/dev/policies.txt
@@ -60,13 +60,13 @@ don't be surprised if the "offending" code gets fiddled over time to
 conform to these conventions.
 
 The Docutils project shall follow the generic coding conventions as
-specified in the `Style Guide for Python Code`_ and `Docstring
-Conventions`_ PEPs, summarized, clarified, and extended as follows:
+specified in the `Style Guide for Python Code` (:PEP:`8`) and `Docstring
+Conventions` (:PEP:`257`), summarized, clarified, and extended as follows:
 
 * 4 spaces per indentation level.  No hard tabs.
 
-* Use only 7-bit ASCII, no 8-bit strings.  See `Docutils
-  Internationalization`_.
+* Use UTF-8 encoding (no encoding declaration).
+  Identifiers must use ASCII only.
 
 * No one-liner compound statements (i.e., no ``if x: return``: use two
   lines & indentation), except for degenerate class or method
@@ -99,9 +99,6 @@ Conventions`_ PEPs, summarized, clarified, and extended as follows:
 * Use 'single quotes' for string literals, and """triple double
   quotes""" for docstrings.
 
-.. _Style Guide for Python Code:
-   https://peps.python.org/pep-0008
-.. _Docstring Conventions: https://peps.python.org/pep-0257
 .. _Docutils Internationalization: ../howto/i18n.html#python-code
 
 
@@ -110,8 +107,7 @@ Documentation Conventions
 
 * Docutils documentation is written using reStructuredText, of course.
 
-* Use 7-bit ASCII if at all possible, and Unicode substitutions when
-  necessary.
+* The encoding of the documentation files is UTF-8.
 
 * Use the following section title adornment styles::
 
-- 
2.30.2

Re: [Docutils-develop] [docutils:feature-requests] #81 0.17.1: pytest is failing

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

Dear Adam, dear Docutils developers,

On 2022-12-02, Adam Turner wrote:

...

> Perhaps we should add ``maxDiff = None`` to all test cases.

To all tests where it applies, yes.
But this might also be done step by step whenever required.


>>     #> pytest-3 --quiet .
>>     [...]


>> * Only 369 out of 1739 tests reported by "alltests.py" are reported.
>>   Is this different counting or does pytest miss more than half of the
>>   tests?

> Different counting -- "sub tests" aren't counted individually by
> default, see ``NumbersTestResult`` in ``alltests.py``.

Ah. So this is because a large number of tests becam "downgraded" to
sub-tests.


...


> I am unsure if we should declare support for this method of running
> tests, whilst it works it may constrain us should we choose e.g. to
> move to ``pytest`` more properly.

We would need to announce this new requirement anyway.
For now, we may just add a caveat, e.g.

diff --git a/docutils/docs/dev/testing.txt b/docutils/docs/dev/testing.txt
index be934a7af..817f20733 100644
--- a/docutils/docs/dev/testing.txt
+++ b/docutils/docs/dev/testing.txt
@@ -40,15 +40,15 @@ In a pinch, the edge cases should cover most of it.
 .. note::
    The ``alltests.py`` test runner is based on the standard library's unittest_
    framework.
-   Since Docutils 0.19, running ``python -m unittest``, the pytest_, and the
-   nose_ frameworks no longer result in spurious failures (cf. `bug #270`_).
-   However, there are differences in the reported number of tests and in
-   test coverage.
+   Since Docutils 0.19, running ``python -m unittest`` and the pytest_
+   framework no longer result in spurious failures (cf. `bug #270`_).
+   However, there are differences in the reported number of tests
+   (``alltests.py`` also counts sub-tests).
+   In future, running the test suite may require pytest_.
 
 __ policies.html#check-ins
 .. _unittest: https://docs.python.org/3/library/unittest.html
 .. _pytest: https://pypi.org/project/pytest
-.. _nose: https://pypi.org/project/nose
 .. _`bug #270`: https://sourceforge.net/p/docutils/bugs/270/
 

>> The "nose" test framework fails, too::

> ``nose`` is unsupported and I don't intend to support it. The
> maintainers don't recommend using it
> (https://nose.readthedocs.io/en/latest/#note-to-users)

OK.

> -----

>> Running idividual test files::

> Must the executable be ``python`` here?  
> ``pytest .\test_parsers\test_rst\test_definition_lists.py`` works, as
> ``pytest`` discovers the root directory as the one containing
> ``setup.cfg`` (or a numer of other sentinel files) and prepends it to
> ``sys.path``. Similarly, ``pytest test_definition_lists.py`` works
> within ``test\test_parsers\test_rst``. 

With the fixes in r9263+, individual test files run fine again.
Switching to pytest is an option for the future 
(would require changing the "shebang line").

> -----

>> trying the test suite on an installation without recommonmark, I
>> stumbled about a new problem:

>>     Traceback (most recent call last):
>>     [...]
>>         raise unittest.SkipTest(f'Cannot test "{md_parser}". '
>>     unittest.case.SkipTest: Cannot test "recommonmark". Parser not found.

>> It seems raising SkipTest is only applicable for test run through the unittest framework (where I am not sure all test run).

> Ahh, we should use ``unittest.defaultTestLoader.discover`` to load
> tests, this respects ``SkipTest``.

Solved now.


Thank you for the work and for the explanations.

Günter

[Docutils-develop] [docutils:patches] #194 Deprecate PEP 263 coding slugs support

[Günter M. <mi...@us...>]

See also the Docutils Enhancement Proposal at https://docutils.sourceforge.io/sandbox/enhancement-proposals/input-encoding/dep-999-input-encoding.txt

The attached patch set implements the changes announced in the RELEASE_NOTES.


Attachments:

- [0003-Document-input-encoding-auto-detection.patch](https://sourceforge.net/p/docutils/patches/_discuss/thread/d27c8d1320/c78d/attachment/0003-Document-input-encoding-auto-detection.patch) (7.4 kB; text/x-patch)
- [0001-Read-binary-data-and-decode-with-heuristics-if-input.patch](https://sourceforge.net/p/docutils/patches/_discuss/thread/d27c8d1320/c78d/attachment/0001-Read-binary-data-and-decode-with-heuristics-if-input.patch) (2.4 kB; text/x-patch)
- [0002-After-detecting-a-BOM-leave-handling-it-to-Python-s-.patch](https://sourceforge.net/p/docutils/patches/_discuss/thread/d27c8d1320/c78d/attachment/0002-After-detecting-a-BOM-leave-handling-it-to-Python-s-.patch) (7.8 kB; text/x-patch)


---

** [patches:#194] Deprecate PEP 263 coding slugs support**

**Status:** open
**Group:** None
**Created:** Thu Jun 09, 2022 10:48 PM UTC by Adam  Turner
**Last Updated:** Sun Jul 24, 2022 08:19 PM UTC
**Owner:** nobody
**Attachments:**

- [0001-Deprecate-PEP-263-coding-slugs.patch](https://sourceforge.net/p/docutils/patches/194/attachment/0001-Deprecate-PEP-263-coding-slugs.patch) (5.5 kB; application/octet-stream)


Python 3 uses utf-8 as the encoding for Python source files, there is no longer a compelling use-case for the support, which adds complexity to the IO implementation.

I propose deprecating support for removal in 1.0, but 2.0 might be a better option.

Support was added in [r4506].

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.

Re: [Docutils-develop] [docutils:feature-requests] #81 0.17.1: pytest is failing

[Adam T. <aat...@ou...>]

Dear Günter,

This note contains replies to all the recent emails in the "0.17.1: pytest is failing" thread.

> On 2022-11-10, Adam Turner via Docutils-develop wrote:

>> With [r9237] the test-suite refactoring project is complete -- using 
>> `pytest` and `python -m unittest` now work "out-of-the-box".

-----

> Run all test tests from the ``test`` directory::
>
>     #> cd REPO-ROOT/docutils/test
>
> Now testing with different methods::
>
>     # ./alltests.py
>     [...]
>
> * All tests run.
> * Test reporting (in case of failures) seems OK.
> * Some diffs only show up after adding ``maxDiff = None`` to the test class
>   definition.

Perhaps we should add ``maxDiff = None`` to all test cases.

-----

> ::
>
>     #> pytest-3 --quiet .
>     [...]
>
>
> * Only 369 out of 1739 tests reported by "alltests.py" are reported.
>   Is this different counting or does pytest miss more than half of the tests?

Different counting -- "sub tests" aren't counted individually by default, see ``NumbersTestResult`` in ``alltests.py``.


> * The warnings show up despite explicit silencing in the code.
>   (Except when we explicitely test for them.)
>   It seems `pytest` bypasses this and reports anyway??

``test_settings`` didn't have the warnings silenced in the ``setUp()`` block.

-----

> Next the standard Python way::
>
>     #> python3.9 -m unittest .
>
> :(

``python -m unittest`` has an odd calling convention. Had you typed ``python -m unittest``, it would've succeeded, as it is shorthand for the 'actual' call of ``python -m unittest discover .``. Adding any arguments means the shorthand isn't used, though.

I am unsure if we should declare support for this method of running tests, whilst it works it may constrain us should we choose e.g. to move to ``pytest`` more properly.

-----

> The "nose" test framework fails, too::

``nose`` is unsupported and I don't intend to support it. The maintainers don't recommend using it (https://nose.readthedocs.io/en/latest/#note-to-users)

-----

> Running idividual test files::
> [...]

> Its a "chicken or egg" problem: the only remaining code in ``DocutilsTestSupport.py`` is adding the "docutils root" and the "test root"
> to sys.path. However, it can only be imported if "test" is recognized as package.

Must the executable be ``python`` here? ``pytest .\test_parsers\test_rst\test_definition_lists.py`` works, as ``pytest`` discovers the root directory as the one containing ``setup.cfg`` (or a numer of other sentinel files) and prepends it to ``sys.path``. Similarly, ``pytest test_definition_lists.py`` works within ``test\test_parsers\test_rst``. 

-----

> trying the test suite on an installation without recommonmark, I stumbled about a new problem:
>     
>     Traceback (most recent call last):
>     [...]
>         raise unittest.SkipTest(f'Cannot test "{md_parser}". '
>     unittest.case.SkipTest: Cannot test "recommonmark". Parser not found.
>
> It seems raising SkipTest is only applicable for test run through the unittest framework (where I am not sure all test run).

Ahh, we should use ``unittest.defaultTestLoader.discover`` to load tests, this respects ``SkipTest``.

Thanks,
Adam

[Docutils-develop] [docutils:feature-requests] #36 option for disallowing file overwrites

[Günter M. <mi...@us...>]

Proposal:

       - <toolname> [options] [<source> [<destination>]] 
       + <toolname> [options] source [source2 [source3 [...]]]

Announce upcoming  changes in Docutils 0.19
   
  * new option ``--output=destination`` in Docutils 0.19
  
  * removal of the short options ``-i`` and ``-o`` in Docutils 1.0
  
  * removal of the second argument `<destination>` in Docutils 2.0

  * accept more than one source document in Docutils 3.0
  
  * short option ``-o`` for ``--output`` in Docutils 3.0     



Attachments:

- [propose-usage-pattern-change.patch](https://sourceforge.net/p/docutils/feature-requests/_discuss/thread/c7e6efb0/0709/attachment/propose-usage-pattern-change.patch) (949 Bytes; text/x-patch)


---

** [feature-requests:#36] option for disallowing file overwrites**

**Status:** pending
**Group:** 
**Created:** Fri Mar 15, 2013 10:43 PM UTC by Jakub Wilk
**Last Updated:** Fri Jul 08, 2022 08:24 AM UTC
**Owner:** nobody


A Debian user complained that if you use a wildcard as input file name, and the wildcard unexpectedly expands to two names, then rst2html will overwrite your files:
http://bugs.debian.org/654690

Would if be possible to add an option for not overwriting output files, that you could add to your configuration file, and later override from command line if needed?



---

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.

[Docutils-develop] [docutils:feature-requests] #88 Unify Docutils CLI tools into `docutils-cli`

[Günter M. <mi...@us...>]

Proposal

* Provide entry point `docutils` (done in 0.19).
* In Docutils 0.20, announce the move from `rst2*.py` scripts to `rst2*` entry points for 0.21 or later.
* For the transition, we already provide `docutils --writer=*` as stable alternative to `rst2*.py` (documented in RELEASE-NOTES since Docutils 0.20). 
* Keep the "rst2*.py" scripts, "rstpep2html.py", and "buildhtml.py" in the `tools/` directory of the repository and source package.

Rationale:

*  installing both, `rst2html` and `rst2html.py` in the binary path would complicate command line use,
*  in scripts, the increased verbosity of the stable command is no problem.
*  changing interactive usage patterns is easy
*  in Windows, it would be bad to first introduce the new "rst2*.py" entry points and then removing them again.
* users installing from the source may install selected front-ends "manually", cf. [docs/dev/repository.txt]( https://docutils.sourceforge.io/docs/dev/repository.html#editable-installs).

The attached patch provides a set of functions that are required for the `rst2*` entry points.
It could go into Docutils 0.20.


Attachments:

- [0001-New-functions-for-use-as-rst2-console_scripts-entry-.patch](https://sourceforge.net/p/docutils/feature-requests/_discuss/thread/bb8ab9be49/9314/attachment/0001-New-functions-for-use-as-rst2-console_scripts-entry-.patch) (34.7 kB; text/x-patch)


---

** [feature-requests:#88] Unify Docutils CLI tools into `docutils-cli`**

**Status:** open
**Group:** Default
**Created:** Sat Jan 15, 2022 10:11 PM UTC by Adam  Turner
**Last Updated:** Fri May 20, 2022 05:53 PM UTC
**Owner:** nobody


As noted at https://sourceforge.net/p/docutils/patches/186/?page=1#897a/547e/ef2d by @milde, 
> we should open a new ticket for the command line tool review

This is a tracker issue for this, and to allow discussion. 

I'll briefly re-outline my argument to (eventually) drop the `rst*` front-end tools, and only export `docutils-cli` (or `python -m docutils`). 

> I think a single front-end tool significantly simplifies a lot of things -- the docutils-cli wrapper is not complex, which gives it significant points in favour in my book.

> Most usage of Docutils today is programmatic, and not via the command line tools (see the table at the bottom of this post - it shows all the projects that have a full dependency on Docutils with over 500k downloads in the last month. Of those 8, none use the command line tools)

> I also suspect (although the data does not exist) that most command line uses of the Docutils tools will be rst2html(5). This is already the default in docutils-cli, so it is a drop-in replacement.

> ...

>  My proposal isn't to remove them *\[the rst2 front-end tools\]* with no recourse, but to deprecate over a period of time, clearly marking identical drop-in commands at runtime to affected users. ... We cannot know how many people would be affected with local random scripts, but it is a two-second change.

> Many users will also run with old or pinned versions of Docutils, and part of updating is seeing the changelog. If Debian or other redistributors already make changes, they could decide to keep shell aliases from rst2* to the new docutils-cli based invocations. 

(quotes taken from https://sourceforge.net/p/docutils/patches/186/#897a and https://sourceforge.net/p/docutils/patches/186/?page=1#897a/547e )

A


---

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.

[Docutils-develop] [docutils:feature-requests] #91 Include directive path argument should support a configurable root.

[Günter M. <mi...@us...>]

New patch including the unit tests and support for "csv-table" directive. Based on [r9293] .
TODO:

* Update documentation for "include", "raw", and "csv-table" directive to document the new behaviour (with links to config.html#include-root).
* Agree on the handling of the "url" argument of the "image" directive when it is interpreted as a local file name (embedded images, LaTeX writer, reading meta-data with PIL). Implement, test, and document it.


Attachments:

- [0001-Config-setting-include-root-configurable-root-direct.patch](https://sourceforge.net/p/docutils/feature-requests/_discuss/thread/a885b6f1ca/9b2b/attachment/0001-Config-setting-include-root-configurable-root-direct.patch) (9.2 kB; text/x-patch)


---

** [feature-requests:#91] Include directive path argument should support a configurable root.**

**Status:** open
**Group:** Default
**Created:** Tue May 03, 2022 04:03 PM UTC by Michal Urbanski
**Last Updated:** Wed Sep 14, 2022 11:48 PM UTC
**Owner:** nobody


I'm building a static website using restructuredtext and I'm really annoyed by the lack of support for root-relative paths.

I have already implemented multiple directive plugins for my website build process, some of which use external files in a different format. They use the convention that if a path begins with /, they are relative to the root directory of the project.

IMO the requirement for relative paths is very limiting - I could have a directory with files intended for inclusion but:

- I would need to use `../../` which is very ugly
- relative paths are different depending on the current file path - this is very fragile and limits 

An additional argument is that C and C++ have been using #include for like 40 years and relative paths (while sometimes useful) are only for specific cases. The leading convention is to use root-relative paths.

I could implement another plugin for it but ... copy-pasting docutils own code only to change few lines is definitely smelly.


---

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.

[Docutils-develop] [docutils:bugs] #461 docutils sdist contains html files in egg-info

[Günter M. <mi...@us...>]

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

The problem is fixed in [r9288],
Thank you for report and analysis. 



---

** [bugs:#461] docutils sdist contains html files in egg-info**

**Status:** open-fixed
**Created:** Wed Nov 16, 2022 02:40 PM UTC by Karolina Surma
**Last Updated:** Wed Nov 16, 2022 02:40 PM UTC
**Owner:** nobody


When packaging docutils 0.19 in Fedora, we realized there are HTML files in the distribution's egg-info (next to the txt "original" ones) which make their way to the wheel too.
```
dependency_links.html
SOURCES.html
top_level.html
```

It looks like something, possibly `tools/buildhtml.py`, makes a batch conversion of the txt files in the project. It should probably ignore the egg-info directory when run.


---

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.

[Docutils-develop] [docutils:patches] #190 Move to native `unittest`

[Adam T. <aa-...@us...>]

- **status**: open-accepted --> closed-accepted



---

** [patches:#190] Move to native `unittest`**

**Status:** closed-accepted
**Group:** None
**Created:** Thu Jan 20, 2022 01:10 AM UTC by Adam  Turner
**Last Updated:** Wed Nov 30, 2022 01:00 PM UTC
**Owner:** nobody


From FR81 https://sourceforge.net/p/docutils/feature-requests/81/#fc55/3d8d by Günter Milde

> I had a quick look and the work looks promising, so yes, I would like to
> give it a try.
> 
> What is the effect on the test time and on the output if there are, e.g.,
> differences between output and expected in functional tests?
> 
> To avoid wasted work (and the sunken-cost fallacy), I propose to split
> the project into smaller changesets (of 1 to ca. 7 commits) which we can
> discuss and adapt before pushing to origin/master and then move to the
> next step.
> I expect some rounds of discussion per step, so there is no
> need to invest heavily in polishing in the first round.
> A link to a patch that I can apply with git am -3 to a local branch
> would be fine.
> The discussion could move to docutils-develop or a new ticket,
> whatever you prefer.

This is the proposed tracking issue for moving to native unittest

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.

[Docutils-develop] [docutils:bugs] #456 Latex Blank lines in Block Math Environment

[Günter M. <mi...@us...>]

Could this be a misunderstanding?
While "no *blank lines*  `"\n\n"` are permitted within an equation or equation* environment",
line breaks (newlines, `"\n"`) are no problem for LaTeX.


---

** [bugs:#456] Latex Blank lines in Block Math Environment**

**Status:** pending-works-for-me
**Created:** Thu Sep 01, 2022 09:14 PM UTC by Daniel James Perry
**Last Updated:** Sat Oct 29, 2022 06:25 PM UTC
**Owner:** nobody


The latex writer has a serious bug regarding block math displays.
According to the book *More Math into Latex*:
> No blank lines are permitted within an equation or equation* environment.

But if you look at the code that's **exactly what it does.** The resulting Latex output is incorrect.
Please fix this as soon as possible.

BTW get with the times and start using git please.


---

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.

[Docutils-develop] [docutils:bugs] #459 Invalid circular inclusion warning when including multiple documents from a directive

[Günter M. <mi...@us...>]

- **status**: pending-works-for-me --> closed-out-of-date
- **Comment**:

Thanks for reporting.

> if I downgrade to 0.16 or upgrade to 0.18 I don't the same build error!

Closing as "out-of-date", as we are working on 0.20 by now.






---

** [bugs:#459] Invalid circular inclusion warning when including multiple documents from a directive**

**Status:** closed-out-of-date
**Created:** Thu Oct 20, 2022 10:30 PM UTC by Ian Wienand
**Last Updated:** Wed Nov 02, 2022 11:05 AM UTC
**Owner:** nobody
**Attachments:**

- [circular-ref-bug.py](https://sourceforge.net/p/docutils/bugs/459/attachment/circular-ref-bug.py) (1.2 kB; text/x-python)


The recent sphinx release has found what I think is a problem in the circular-reference detection in docutils.

We have a situation where we build a page with a directive that automatically includes a file (readme from a sub-component).  In some cases, these readme's might then also include another file (e.g. similar components share a common file about their arguments, etc.).  So we have a include hierarchy like

~~~
 .. include:: ./component/README.rst
   .. include:: common.rst
.. include:: ./component2/README.rst
  .. include:: common.rst
~~~

Our directive works by reading the `README.rst` file and then using `self.state_machine.insert_input()`

Our build started failing due a `circular inclusion in "include" directive` which comes from the *second* inclusion of the `common.rst` above.  In this situation, I don't believe there is any circular inclusion -- we want the same content included twice; but it is not referencing itself.

I think it has something to do with `self.state.document.include_log` thinking that it has seen `common.rst` before.

I have isolated this down to the smallest example I can think of and attached that; it is also at https://paste.opendev.org/show/brTxHYllHebBIs1wHbfM/

When I run this I get

~~~
$ ./docutils-venv/bin/python3 ./recursive.py 
Write combined.rst
Write file1.rst
Write file2.rst
Write common.rst
file1.rst:1: (WARNING/2) circular inclusion in "include" directive:
file1.rst
> file1.rst
~~~



---

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.

[Docutils-develop] [docutils:bugs] #460 default settings do not provide required settings values

[Günter M. <mi...@us...>]

> I suppose I'm still unclear on the delineation between reader and parser. 

The components are explained in chapter [Docutils Project Model](https://docutils.sourceforge.io/docs/peps/pep-0258.html#docutils-project-model) in PEP 258.

When using the core API ([the Docutils publisher](https://docutils.sourceforge.io/docs/api/publisher.html)), settings are automatically set up for the specified components.
For details, see the docstrings of the `docutils.core.publish_*()` functions, 
[Docutils Runtime Settings](https://docutils.sourceforge.io/docs/api/runtime-settings.html),
or the  more detailed [Runtime Settings Processing](https://docutils.sourceforge.io/docs/api/runtime-settings.html).

To find out which components define which settings, you can also just call `docutils --help`.

Suggestions for improving the documentation are welcome.


---

** [bugs:#460] default settings do not provide required settings values**

**Status:** open
**Labels:** standalone reader 
**Created:** Sat Nov 12, 2022 02:17 AM UTC by Ryan de Kleer
**Last Updated:** Wed Nov 16, 2022 06:32 PM UTC
**Owner:** nobody


# Platform
Windows 10
Python 3.7
docutils 0.19.1b.dev

# Issue
Generating a document with the standalone reader fails with default settings.

# Example
```python
from docutils.readers import standalone
from docutils.parsers import rst
from docutils import io
from docutils.frontend import get_default_settings

from docutils import __version__

rst_src = """
A Document
----------
Simple but enough.
"""

def try_this():
    print(__version__)

    src = io.StringInput(rst_src)
    parser = rst.Parser()
    reader = standalone.Reader(parser=parser)
    settings = get_default_settings(reader)
    document = reader.read(src, parser, settings)
    
 try_this()
```

Results in:

```python
0.19.1b.dev
Traceback (most recent call last):
 line 19, in try_this
    document = reader.read(src, parser, settings)
 
 ...
 
File "docutils/parsers/rst/states.py", line 607, in init_customizations
    if settings.pep_references:
AttributeError: 'Values' object has no attribute 'pep_references'
```




---

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.