Parameters are uppercased when rendering doc-strings with Numpydoc

[john-hen]

When using the Sphinx extension Numpydoc alongside Autodoc to render NumPy-style doc-strings, parameter names and their types appear in uppercase on the page, regardless of how they are defined in the code.

To reproduce, create this conf.py

extensions = ['sphinx.ext.autodoc', 'numpydoc']
html_theme = 'furo'
import sys
sys.path.insert(0, '.')

this index.rst

.. automodule:: module
    :members:

and this module.py

def function(index, text):
    """
    Doc-string with parameter list in NumPy style.

    Parameters
    ----------
    index: int
        An index number.
        
    text : str
        Some text.
    """

Then run sphinx-build . output in the same folder. The output is this:

The parameter names and types are in all-caps, which is probably not intended, given how confusing that might be in API documentation.

The reason seems to be that the CSS selector dl.py .field-list dt defined by Furo in _api.sass applies text-transform: uppercase not just to the "Parameters" heading, but also to the list items rendered by Numpydoc as the following HTML:

<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><dl class="simple">
<dt><strong>index: int</strong></dt>
<dd><p>An index number.</p></dd>
<dt><strong>text</strong><span class="classifier">str</span></dt>
<dd><p>Some text.</p></dd>
</dl></dd></dl>

Instead of Numpydoc, we can also render Numpy-style doc-strings with Napoleon, simply by replacing 'numpydoc' with 'sphinx.ext.napoleon' in conf.py. Then parameter names are properly cased as Napoleon produces this HTML:

<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>index</strong> (<em>int</em>) – An index number.</p></li>
<li><p><strong>text</strong> (<em>str</em>) – Some text.</p></li>
</ul></dd></dl>

Tested with Furo 2021.10.9, Numpydoc 1.1.0, Sphinx 4.2.0.

See also:

• Earlier discussion here, numpydoc style parameters and attributes wrongly uppercased #200, missing a reproducible example.
• Stack Overflow question that prompted this report.

[pradyunsg]

Fixed in 20a83d1, I think.

Can you pip install https://github.com/pradyunsg/furo/archive/refs/heads/main.zip and confirm whether that fix works?

[john-hen]

Full disclosure, I can't seem to get Furo to build from source on either Windows or Ubuntu. (And for different reasons according to the error messages.) So I just edited the > child selector into the minimized furo.css in Furo 2021.11.23 as installed from PyPI.

But then it works. 👍 Everything looking good with Numpydoc, Napoleon, and field lists.

[pradyunsg]

If you could share the errors in a new discussion topic, that would be great!