Revert "Mark test_build_manpage as XFAIL following changes in Doc…

[jfbu]

…utils master"

This reverts commit 1ed4ca7.

We have currently 3 test failures on DocUtils HEAD (currently at r9852).

Two of them come from a XFAIL because DocUtils master version is currently at 0.22b.dev. The tests failed at some earlier stage of DocUtils master after their 0.21.2 but now currently they do not.

The third failure is tests/test_builders/test_build_latex.py::test_one_parameter_per_line and comes from typing annotations added at Docutils revision r9813.

I am not addressing this here, also because I found what appears to be a bug in PDF output, which is unrelated to that recent failure but displayed by the test.

[AA-Turner]

The third failure is tests/test_builders/test_build_latex.py::test_one_parameter_per_line and comes from typing annotations added at Docutils revision r9813.

I can revert part of that commit if needed (or commit a patch to Docutils to fix the underlying problem, if you have one)

A

[jfbu]

@AA-Turner I will ping @picnixz for possibly updating the test_build_latex.py::test_one_parameter_per_line test but first I must open a separate issue because it seems there is a problem with PDF output which I discovered when applying pdflatex to the produced tex file.

[jfbu]

@AA-Turner There is (I believe) a pre-existing problem with py:class directive #12735, it is unrelated to the added typing annotations at DocUtils so it is a good thing that this DocUtils change at master caused a test failure in our test suite which incited me to process the file via pdflatex. The fact the problem shows with python_maximum_signature_line_length = 23 but not python_maximum_signature_line_length = 1 endangered my mental health because the 23 is set in our test via an override, so the problem showed when I used pdflatex on the tex file produced via this override, but not when I copied over the sources and tested them outside of pytest directories via make latexpdf which applied the conf.py =1 setting...

[jfbu]

@AA-Turner

I have fixed #12735, but the test will need update to pass on DocUtils HEAD. Here is for info the induced changes in output tex file: (green lines are with DocUtils HEAD, red ones with 0.21.2).

--- /.../pytest-of-someone/pytest-68/domain-py-python_maximum_signature_line_length/_build/latex/projectnamenotset.tex	2024-08-05 17:26:31.000000000 +0200
+++ /.../pytest-of-someone/pytest-67/domain-py-python_maximum_signature_line_length/_build/latex/projectnamenotset.tex	2024-08-05 17:19:40.000000000 +0200
@@ -90,7 +90,7 @@
 \pysigstartsignatures
 \pysiglinewithargsret
 {\sphinxbfcode{\sphinxupquote{hello}}}
-{\sphinxparam{\DUrole{n}{name}\DUrole{p}{:}\DUrole{w}{ }\DUrole{n}{str}}}
+{\sphinxparam{\DUrole{n,n}{name}\DUrole{p,p}{:}\DUrole{w,w}{ }\DUrole{n,n}{str}}}
 {{ $\rightarrow$ str}}
 \pysigstopsignatures
 \end{fulllineitems}
@@ -102,7 +102,7 @@
 \pysigstartsignatures
 \pysigwithonelineperarg
 {\sphinxbfcode{\sphinxupquote{foo}}}
-{\sphinxoptional{\sphinxparam{\DUrole{n}{a}}\sphinxparamcomma \sphinxoptional{\sphinxparam{\DUrole{n}{b}}\sphinxparamcomma }}\sphinxparam{\DUrole{n}{c}}\sphinxparamcomma \sphinxparam{\DUrole{n}{d}}\sphinxoptional{\sphinxparamcomma \sphinxparam{\DUrole{n}{e}}\sphinxparamcomma \sphinxparam{\DUrole{n}{f}}\sphinxparamcomma }}
+{\sphinxoptional{\sphinxparam{\DUrole{n,n}{a}}\sphinxparamcomma \sphinxoptional{\sphinxparam{\DUrole{n,n}{b}}\sphinxparamcomma }}\sphinxparam{\DUrole{n,n}{c}}\sphinxparamcomma \sphinxparam{\DUrole{n,n}{d}}\sphinxoptional{\sphinxparamcomma \sphinxparam{\DUrole{n,n}{e}}\sphinxparamcomma \sphinxparam{\DUrole{n,n}{f}}\sphinxparamcomma }}
 {}
 \pysigstopsignatures
 \end{fulllineitems}
@@ -114,7 +114,7 @@
 \pysigstartsignatures
 \pysiglinewithargsretwithtypelist
 {\sphinxbfcode{\sphinxupquote{generic\_arg}}}
-{\sphinxtypeparam{\DUrole{n}{T}}}
+{\sphinxtypeparam{\DUrole{n,n}{T}}}
 {}
 {}
 \pysigstopsignatures
@@ -127,7 +127,7 @@
 \pysigstartsignatures
 \pysiglinewithargsretwithtypelist
 {\sphinxbfcode{\sphinxupquote{generic\_foo}}}
-{\sphinxtypeparam{\DUrole{n}{T}}}
+{\sphinxtypeparam{\DUrole{n,n}{T}}}
 {}
 {}
 \pysigstopsignatures
@@ -140,8 +140,8 @@
 \pysigstartsignatures
 \pysigwithonelineperargwithtypelist
 {\sphinxbfcode{\sphinxupquote{generic\_bar}}}
-{\sphinxtypeparam{\DUrole{n}{T}}}
-{\sphinxparam{\DUrole{n}{x}\DUrole{p}{:}\DUrole{w}{ }\DUrole{n}{list\DUrole{p}{{[}}T\DUrole{p}{{]}}}}\sphinxparamcomma }
+{\sphinxtypeparam{\DUrole{n,n}{T}}}
+{\sphinxparam{\DUrole{n,n}{x}\DUrole{p,p}{:}\DUrole{w,w}{ }\DUrole{n,n}{list\DUrole{p,p}{{[}}T\DUrole{p,p}{{]}}}}\sphinxparamcomma }
 {}
 \pysigstopsignatures
 \end{fulllineitems}
@@ -153,7 +153,7 @@
 \pysigstartsignatures
 \pysiglinewithargsretwithtypelist
 {\sphinxbfcode{\sphinxupquote{generic\_ret}}}
-{\sphinxtypeparam{\DUrole{n}{R}}}
+{\sphinxtypeparam{\DUrole{n,n}{R}}}
 {}
 {{ $\rightarrow$ R}}
 \pysigstopsignatures
@@ -165,8 +165,8 @@
 \phantomsection\label{\detokenize{index:MyGenericClass}}
 \pysigstartsignatures
 \pysiglinewithargsretwithtypelist
-{\sphinxbfcode{\sphinxupquote{class\DUrole{w}{ }}}\sphinxbfcode{\sphinxupquote{MyGenericClass}}}
-{\sphinxtypeparam{\DUrole{n}{X}}}
+{\sphinxbfcode{\sphinxupquote{class\DUrole{w,w}{ }}}\sphinxbfcode{\sphinxupquote{MyGenericClass}}}
+{\sphinxtypeparam{\DUrole{n,n}{X}}}
 {}
 {}
 \pysigstopsignatures
@@ -178,8 +178,8 @@
 \phantomsection\label{\detokenize{index:MyList}}
 \pysigstartsignatures
 \pysiglinewithargsretwithtypelist
-{\sphinxbfcode{\sphinxupquote{class\DUrole{w}{ }}}\sphinxbfcode{\sphinxupquote{MyList}}}
-{\sphinxtypeparam{\DUrole{n}{T}}}
+{\sphinxbfcode{\sphinxupquote{class\DUrole{w,w}{ }}}\sphinxbfcode{\sphinxupquote{MyList}}}
+{\sphinxtypeparam{\DUrole{n,n}{T}}}
 {\sphinxparam{list{[}T{]}}}
 {}
 \pysigstopsignatures

Thus, the sole changes are duplications of arg of \DUrole. I have not tried to find its origin.

Actually \DUrole does nothing at all in Sphinx. It is a legacy mark-up macro which allows custom styling, a bit like CSS class in HTML. For example \DUrole{n} will try LaTeX command \DUrolen if it exists or \docutilsrolen as fall-back or will do nothing if neither exists.

With \DUrole{n,n}, it will thus try to use a LaTeX command of name \DUrolen,n where the comma is part of the command name (you need a special LaTeX construct to obtain such a name). Those things are for people adding custom styling via this mark-up. Chances are, nobody uses any of this mark-up.

But if they existe then the n->n,n is breaking.

Perhaps there is also duplication in HTML output which I have not checked yet but is probable.

On LaTeX side, we could consider removing entirely any \DUrole mark-up, I wonder if any external tool exists relying on its customizing possibility. On the other hand it offers hook points for some design hacks.

But clearly the duplication is then a problem. The reST source for this is test/test_builders/text_build_latex.py::test_one_parameter_per_line, i.e. it uses

.. py:function:: hello(name: str) -> str

.. py:function:: foo([a, [b, ]]c, d[, e, f])

.. py:function:: generic_arg[T]

.. py:function:: generic_foo[T]()

.. py:function:: generic_bar[T](x: list[T])

.. py:function:: generic_ret[R]() -> R

.. py:class:: MyGenericClass[X]

.. py:class:: MyList[T](list[T])

with confoverrides={'python_maximum_signature_line_length': 23}

[jfbu]

\DUrole in inserted by LaTeX writer via the visit_inline() method:

sphinx/sphinx/writers/latex.py

Lines 2175 to 2177 in 05cc39d

	elif classes and not self.in_title:
	self.body.append(r'\DUrole{%s}{' % ','.join(classes))
	self.context.append('}')

It is very analogous to old-style styling via <span></span in HTML and thus potentially useful. It has no documentation whatsover but a CHANGES entry at 1.4 (#2231) and at 1.5 (#3207).

DocUtils documentation about \DUrole.

[jfbu]

Pseudoxml shows the duplication of classes:

        <desc classes="py class" desctype="class" domain="py" no-contents-entry="0" no-index="0" no-index-entry="0" no-typesetting="0" nocontentsentry="0" noindex="0" noindexentry="0" objtype="class">
            <desc_signature _toc_name="MyGenericClass" _toc_parts="MyGenericClass" class="" classes="sig sig-object py" fullname="MyGenericClass" ids="MyGenericClass" module="True">
                <desc_annotation xml:space="preserve">
                    class
                    <desc_sig_space classes="w w">
                         
                <desc_name classes="sig-name descname" xml:space="preserve">
                    MyGenericClass
                <desc_type_parameter_list multi_line_parameter_list="1" xml:space="preserve">
                    <desc_type_parameter xml:space="preserve">
                        <desc_sig_name classes="n n">
                            T

but it is somehow resolved by HTML writer.

[jfbu]

@AA-Turner I have understood partly the problem. In docutils.nodes the __init__ method of the TextElement class now does super.__init__(). Turns out (for reasons I have not investigated) that this will activate the Sphinx addnodes._desc_classes_injector.__init__().

When (for example) addnodes.desc_sig_space() __init__() is triggered it has set self.classes to ['w']. When the injector is activated it transfers this to a 'classes' attribute, and then we are back to desc_sig_element.__init()__ which does self['classes'].extend(self.classes) hence the duplication.

Naive changes to current DocUtils nodes.py to make it more like the one at 0.21.2 such as replacing the super().__init__( in class TextElement(Element): by Element.__init__( creates errors, so I could not confirm this would avoid triggering our addnodes._desc_classes_injector.__init(). But I am certain the problem is that this TextElement super().__init__ activates the Sphinx addnodes._desc_classes_injector.

EDIT: my attempt at restoring Element. in place of super(). in Docutils nodes.TextElement() should have succeeded except I had forgotten to also inject self as first parameter.

[AA-Turner]

cc @picnixz as author of addnodes._desc_classes_injector. I can revert the change in Docutils with ease, but changing from Element.__init__() to super().__init__ is generally safe!

A

[AA-Turner]

@jfbu I reverted the change in Docutils: https://sourceforge.net/p/docutils/code/9859/

Does this help things?

A

[jfbu]

@AA-Turner Yes it does fix the problem of duplicated classes. I initially applied your patch only partially forgetting the self (because git pull did not fetch it yet from docutils git mirror.)