Docutils 0.18 and Sphinx

[Guenter Milde]

Dear Takeshi, dear Sphinx developers,

thank you for the backport releases adding a pin to a maximum Docutils
version to Sphinx series 1 and 2.

On 21.11.21, Takeshi KOMIYA wrote on github (Issue #9807):

> IMO, docutils-0.18.1 resolves some of the troubles. But some of them
> will not be resolved. That's the reason why the latest Sphinx does not
> still support docutils-0.18.

How can we help here?
What are the remaining problems?



I tried the combination Sphinx 3.4.3 (from Debian/stable) with
Docutils 0.18.1b for the documentation of https://repo.or.cz/pylit.git and
managed to get an acceptable result:

* There are 0 errors and 1 warning:

WARNING: while setting up extension sphinx.addnodes: node class
'meta' is already registered, its visitors will be overridden

Since 0.18, <meta> is a standard node, so the re-registration by Sphinx
can be skipped ``if docutils_version >= (0, 18)``.

* In the HTML, there are two ``<meta name="viewport" ...>`` nodes.
One from Sphinx::

<meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" />

and one added by the Docutils HTML5 writer (since 0.18)::

<meta name="viewport" content="width=device-width, initial-scale=1.0" />


* Footnotes were unstyled, because they use different HTML tags since 0.18.

I could fix this in my custom CSS style sheet.
In conf.py::

html_style = 'pylit-sphinx.css'

And the following lined from docutils/writers/html5_polyglot/minimal.css
copied to pylit-sphinx.css::

/* Footnotes and Citations */
.footnote {
font-size: small;
}
.footnote, .citation { margin: 1em 0; } /* default paragraph skip (Firefox) */
/* hanging indent */
.citation { padding-left: 2em; }
.footnote { padding-left: 1.7em; }
.footnote.superscript { padding-left: 0.9em; }
.citation > .label { margin-left: -2em; }
.footnote > .label { margin-left: -1.7em; }
.footnote.superscript > .label { margin-left: -0.9em; }

.footnote > .label + *,
.citation > .label + * {
display: inline-block;
margin-top: 0;
vertical-align: top;
}
.footnote > .backrefs + *,
.citation > .backrefs + * {
margin-top: 0;
}
.footnote > .label + p, .footnote > .backrefs + p,
.citation > .label + p, .citation > .backrefs + p {
display: inline;
vertical-align: inherit;
}

.backrefs > a { font-style: italic; }

Adding these lines to "spinxdoc.css" may solve this issue in Sphinx 1.4.x.
If the style variant with superscript footnotes shall be supported out of
the box, also::

/* superscript footnotes */
a[role="doc-noteref"].superscript,
.footnote.superscript > .label,
.footnote.superscript > .backrefs {
vertical-align: super;
font-size: smaller;
line-height: 1;
}
a[role="doc-noteref"].superscript > .fn-bracket,
.footnote.superscript > .label > .fn-bracket {
/* hide brackets in display but leave for copy/paste */
display: inline-block;
width: 0;
overflow: hidden;
}
[role="doc-noteref"].superscript + [role="doc-noteref"].superscript {
padding-left: 0.15em; /* separate consecutive footnote references */
/* TODO: unfortunately, "+" also selects with text between the references. */
}

I hope we can get a smoot and stable co-operation of Sphinx and Docutils.

Thanks,
Günter Milde

[Komiya Takeshi]

Hi,

To support docutils-0.18.x, we need to resolve the errors here:
https://github.com/sphinx-doc/sphinx/actions/workflows/docutils-latest.yml

I need to find time to fix them.

Thanks,
Takeshi KOMIYA

Thanks,
Takeshi KOMIYA

2021年11月23日(火) 6:41 Guenter Milde <mi...@users.sf.net>:

> --
> You received this message because you are subscribed to the Google Groups "sphinx-dev" group.
> To unsubscribe from this group and stop receiving emails from it, send an email to sphinx-dev+...@googlegroups.com.
> To view this discussion on the web, visit https://groups.google.com/d/msgid/sphinx-dev/snh2qp%24trl%241%40ciao.gmane.io.

[Guenter Milde]

Dear Takeshi,

thank you for the fast reply.

On 2021-11-23, Komiya Takeshi wrote:

> To support docutils-0.18.x, we need to resolve the errors here:
> https://github.com/sphinx-doc/sphinx/actions/workflows/docutils-latest.yml

I'd like to find out what could be done on the Docutils side to resolve the
errors.

Unfortunately, I cannot find an error log there (not even after loggin in
to github), only (after some clicking around) ``Process completed with
exit code 1.`` and, the workflow file.

Could you post a the error description or log (or a link to), please.


Thanks,
Günter Milde

[Vinay Sajip]

Perhaps this will help:

============================= test session starts ==============================
platform linux -- Python 3.10.0, pytest-6.2.5, py-1.11.0, pluggy-1.0.0 -- /home/runner/work/sphinx/sphinx/.tox/du-latest/bin/python
cachedir: .tox/du-latest/.pytest_cache
libraries: Sphinx-4.4.0+/7d7c59a, docutils-0.18.1b1.dev
base tempdir: /tmp/pytest-of-runner/pytest-0
rootdir: /home/runner/work/sphinx/sphinx, configfile: setup.cfg, testpaths: tests
plugins: cov-3.0.0
collecting ... collected 1738 items / 1 error / 1737 selected
==================================== ERRORS ====================================
__________________ ERROR collecting tests/test_versioning.py ___________________
tests/test_versioning.py:21: in <module>
meta = MetaBody.meta
E AttributeError: type object 'MetaBody' has no attribute 'meta'
=============================== warnings summary ===============================
tests/test_versioning.py:20
/home/runner/work/sphinx/sphinx/tests/test_versioning.py:20: DeprecationWarning: The `docutils.parsers.rst.directive.html` module will be removed in Docutils 1.2. Since Docutils 0.18, the "Meta" node is defined in `docutils.parsers.rst.directives.misc`.
from docutils.parsers.rst.directives.html import MetaBody
-- Docs: docs.pytest.org/en/stable/warnings.html
=========================== short test summary info ============================
ERROR tests/test_versioning.py - AttributeError: type object 'MetaBody' has n...
!!!!!!!!!!!!!!!!!!!! Interrupted: 1 error during collection !!!!!!!!!!!!!!!!!!!!
========================= 1 warning, 1 error in 11.66s =========================
ERROR: InvocationError for command /home/runner/work/sphinx/sphinx/.tox/du-latest/bin/python -X dev -m pytest --durations 25 -vv (exited with code 2)
___________________________________ summary ____________________________________
ERROR: du-latest: commands failed
Error: Process completed with exit code 1.

--
You received this message because you are subscribed to the Google Groups "sphinx-dev" group.
To unsubscribe from this group and stop receiving emails from it, send an email to sphinx-dev+...@googlegroups.com.

To view this discussion on the web, visit https://groups.google.com/d/msgid/sphinx-dev/snil3i%2415gj%241%40ciao.gmane.io.

[Juan Luis Cano Rodríguez]

Link to the logs: https://github.com/sphinx-doc/sphinx/runs/4275767635?check_suite_focus=true#step:8:54

Cheers,

jua...@readthedocs.org

Read the Docs

[Guenter Milde]

On 2021-11-23, 'Vinay Sajip' via sphinx-dev wrote:
> Perhaps this will help:
...

> __________________ ERROR collecting tests/test_versioning.py ___________________
> tests/test_versioning.py:21: in <module>
> meta = MetaBody.meta
> E AttributeError: type object 'MetaBody' has no attribute 'meta'

It helps.

"meta" is now a standard class, the definition moved from
``docutils.parsers.rst.directives.html.MetaBody.meta`` to
``docutils.nodes.meta``.

If Spinx itself contians code relying on the old name, Docutils will
introduce an alias for backwards compatibility.

In the test code, I recommend a switch::

if docutils.version_info < (0, 18):
meta = MetaBody.meta
else
meta = nodes.meta


Thanks,
Günter Milde