Add an option to not create links within a sig-param block

[mattip]

Describe the bug

Over at Pytorch/vision, we moved from Sphinx 2.x to Sphinx 3.5.4. When rendering python functions with annotations, the rendering looks like this (the raw html is in the detail, broken up by lines).

class torchvision.datasets.Caltech101(root: str, target_type: Union[List[str], str] = 'category', transform: Optional[Callable] = None, target_transform: Optional[Callable] = None, download: bool = False)[source]

We have a few concerns, the primary one is:

• I couldn't find an option to remove the links to str and bool, we really do not need them and the link formatting is distracting.

Also problematic, but much less so:

• The formatting makes the page heavier than it needs to be. Is there a way to avoid having so many spans?
• Spaces are not part of the spans, they are one level up. This greatly reduces the ability to use css formatting, perhaps the "p" class could include the spaces or (maybe better) there is no need for the "p" class, it could be handled like the spaces by the class="sig-param" container.

raw html

<dt id="torchvision.datasets.Caltech101">
<em class="property"><span class="pre">class</span> </em>
<code class="sig-prename descclassname"><span class="pre">torchvision.datasets.</span></code>
<code class="sig-name descname"><span class="pre">Caltech101</span></code>
<span class="sig-paren">(</span>
<em class="sig-param">
    <span class="n"><span class="pre">root</span></span>
    <span class="p"><span class="pre">:</span></span> 
    <span class="n"><a class="reference external has-code" href="https://docs.python.org/3/library/stdtypes.html#str" title="(in Python v3.9)"><span class="pre">str</span></a></span>
</em>
, 
<em class="sig-param">
    <span class="n"><span class="pre">target_type</span></span>
    <span class="p"><span class="pre">:</span></span> 
    <span class="n">
        <span class="pre">Union</span>
        <span class="p"><span class="pre">[</span></span>
        <span class="pre">List</span>
        <span class="p"><span class="pre">[</span></span>
        <a class="reference external has-code" href="https://docs.python.org/3/library/stdtypes.html#str" title="(in Python v3.9)"><span class="pre">str</span></a>
        <span class="p"><span class="pre">]</span></span>
        <span class="p"><span class="pre">,</span> </span>
        <a class="reference external has-code" href="https://docs.python.org/3/library/stdtypes.html#str" title="(in Python v3.9)"><span class="pre">str</span></a>
        <span class="p"><span class="pre">]</span></span>
    </span> 
    <span class="o"><span class="pre">=</span></span> 
    <span class="default_value"><span class="pre">'category'</span></span>
</em>, 
<em class="sig-param">
    <span class="n"><span class="pre">transform</span></span>
    <span class="p"><span class="pre">:</span></span> 
    <span class="n">
        <span class="pre">Optional</span>
        <span class="p"><span class="pre">[</span></span>
        <span class="pre">Callable</span>
        <span class="p"><span class="pre">]</span></span>
     </span> 
     <span class="o"><span class="pre">=</span></span> 
    <span class="default_value"><span class="pre">None</span></span>
</em>, 
<em class="sig-param">
    <span class="n"><span class="pre">target_transform</span></span>
    <span class="p"><span class="pre">:</span></span> 
    <span class="n">
        <span class="pre">Optional</span>
        <span class="p"><span class="pre">[</span></span>
        <span class="pre">Callable</span>
        <span class="p"><span class="pre">]</span></span>
    </span> 
    <span class="o"><span class="pre">=</span></span> 
    <span class="default_value"><span class="pre">None</span></span>
</em>, 
<em class="sig-param">
    <span class="n"><span class="pre">download</span></span>
    <span class="p"><span class="pre">:</span></span> 
    <span class="n">
         <a class="reference external has-code" href="https://docs.python.org/3/library/functions.html#bool" title="(in Python v3.9)"><span class="pre">bool</span></a>
      </span> 
      <span class="o"><span class="pre">=</span></span> 
      <span class="default_value"><span class="pre">False</span></span>
</em>
<span class="sig-paren">)</span>
<a class="reference internal has-code" href="_modules/torchvision/datasets/caltech.html#Caltech101"><span class="viewcode-link"><span class="pre">[source]</span></span></a>
<a class="anchorjs-link " aria-label="Anchor" data-anchorjs-icon="" href="#torchvision.datasets.Caltech101" style="font: 1em / 1 anchorjs-icons; padding-left: 0.375em;"></a>
</dt>

How to Reproduce

$ git clone https://github.com/pytorch/vision
$ cd vision/docs
$ pip install -r requirements.txt
$ make html
$ # open _build/html/datasets.html

Expected behavior

I would expect there to be an option to disable creating links, an option to create light-weight signatures, or something along those lines.

It would also be helpful to have a "guide to formatting" that describes the various classes available for formatting. In this example there are "anchorjs-link ", "default_value", "n", "o","p", "pre", "property", "reference external has-code","reference internal has-code", "sig-name descname", "sig-param", "sig-paren", "sig-prename descclassname", "viewcode-link"

Your project

https://github.com/pytorch/vision/tree/main/docs

Screenshots

No response

OS

linux

Python version

3.8

Sphinx version

3.5.4

Sphinx extensions

'sphinx.ext.autodoc', 'sphinx.ext.autosummary', 'sphinx.ext.doctest', 'sphinx.ext.intersphinx', 'sphinx.ext.todo', 'sphinx.ext.mathjax', 'sphinx.ext.napoleon', 'sphinx.ext.viewcode', 'sphinx.ext.duration', 'sphinx_gallery.gen_gallery', 'sphinx_copybutton'

Extra tools

No response

Additional context

We use the pytorch_sphinx_theme based on the RTD theme. Here is the issue that triggered this report pytorch/pytorch_sphinx_theme#139

[astrojuanlu]

Would removing this line https://github.com/pytorch/vision/blob/57725901bdc59530670813e07f61423702051845/docs/source/conf.py#L201 be a valid solution for you?

[mattip]

That would remove all the other python intersphinx mapping that we desire to use, so no, it would not be a valid solution as far as I can tell.

[jakobandersen]

• I couldn't find an option to remove the links to str and bool, we really do not need them and the link formatting is distracting.

(I can't immediately compile the docs as the package is not found during make html. Is there a compiled version online somewhere?)
I think it gets icky to disable this at the Python domain level, and I'm not sure that would be the right solution. Could it be resolved by changing the CSS in your theme to render those particular links in a less distracting manner? (and see below how that may be done)

• The formatting makes the page heavier than it needs to be. Is there a way to avoid having so many spans?

I think all the spans are needed to be able to customize through CSS by theme authors. Do you have particular examples of superfluous ones?

• Spaces are not part of the spans, they are one level up. This greatly reduces the ability to use css formatting, perhaps the "p" class could include the spaces or (maybe better) there is no need for the "p" class, it could be handled like the spaces by the class="sig-param" container.

This is indeed a problem and, e.g., the RTD theme has some CSS that broke some declarations due to this (see e.g., breathe-doc/breathe#655).
Some extra docutils nodes were added in #9023, and I converted the C and C++ domains to use these. Changing the Python domain to use these nodes should solve this space issue. Assuming @tk0miya is ok with this approach, I can give a go at some point when I find time, but if anyone else wants to start it, please just start a PR.

It would also be helpful to have a "guide to formatting" that describes the various classes available for formatting. In this example there are "anchorjs-link ", "default_value", "n", "o","p", "pre", "property", "reference external has-code","reference internal has-code", "sig-name descname", "sig-param", "sig-paren", "sig-prename descclassname", "viewcode-link"

Indeed, and I think once the Python domain uses more of the above-mentioned docutils nodes I believe we can be a nice structured guide for styling the declarations (perhaps that reveals a bit more cleanup in the CSS classes is needed). #9023 may provide some hints for now, and at

sphinx/sphinx/themes/basic/static/basic.css_t

Line 546 in 6c38f68

/* C++ specific styling */

you can see how the C and C++ declarations are styled using this (though it definitely doesn't use all of the classes you mentioned).

[mattip]

Could it be resolved by changing the CSS in your theme to render those particular links in a less distracting manner? (and see below how that may be done)

This is probably the best path for now, thanks.

I think all the spans are needed to be able to customize through CSS by theme authors. Do you have particular examples of superfluous ones?

This annotation Caltech101(root: str) I think gets turned into this annotation (starting from the opening parethesis:

<code class="sig-name descname"><span class="pre">Caltech101</span></code>
<span class="sig-paren">(</span>
<em class="sig-param">
    <span class="n"><span class="pre">root</span></span>
    <span class="p"><span class="pre">:</span></span> 
    <span class="n"><a class="reference external has-code" href="https://docs.python.org/3/library/stdtypes.html#str" title="(in Python v3.9)"><span class="pre">str</span></a></span>
</em>
<span class="sig-paren">)</span>

I think the open and closing parenthesis (sig-paren) could be removed, and that the "n" and "p" spans do not need additional "pre" spans inside them.

[mattip]

This project is indeed difficult to build, sorry for that. The only easy way to get the project is via conda using the conda install -c pytorch torchvision command, but even that does not get a nightly build, so the documentation may not match. You can see the rendered content at https://pytorch.org/vision/master/datasets.html#caltech. Note that the page will be updated within 12 hours from sphinx 2.X to 3.5.4 following merging pytorch/vision#4318 and the subsequent nightly build, which triggered my opening this issue

[jakobandersen]

I think the open and closing parenthesis (sig-paren) could be removed, and that the "n" and "p" spans do not need additional "pre" spans inside them.

Thanks for the example. If I remember correct then the sig-paren is used to make the parens for outer function paramter lists slightly larger, similarly to how the sig-name/descname is making the main name of the declared entity slightly larger, bold, or whatever style.

As for the pre spans: yes! your example triggered my memory. I tried to find a way to get rid of them during #9023, but how I remember it is that all the things I tried would break, e.g., the Python domain. I suggest looking into a solution for this after the update the Python domain to use more docutils nodes.

As a comparison for how the HTML will look after this update, you can compare to a similar C++ signature, e.g., https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#_CPPv4NK16overload_example1C1fEd which becomes the following (currently with the extra pre spans).

<span class="kt"><span class="pre">void</span></span>
<span class="w"> </span>
<span class="sig-name descname">
	<span class="n"><span class="pre">f</span></span>
</span>
<span class="sig-paren">(</span>
<span class="kt"><span class="pre">double</span></span>
<span class="w"> </span>
<span class="n sig-param"><span class="pre">d</span></span>
<span class="sig-paren">)</span>
<span class="w"> </span>
<span class="k"><span class="pre">const</span></span>