Search code examples
pythonthemespython-sphinxdocumentation-generation

Furo Sphinx theme uppercases too much in API documentation

I am a beginner in documentation with Sphinx. I wanted to produce numpy style documentations. Therefore, I used numpydoc extension. Numpy uses pydata theme, however I chose furo. I understand that there will be some differences in appearance, but I expected my page to have the same format as numpy's at least, though I get the parameter names, and types capitalized. Descriptions are not capitalized.

My docstring:

def translate_pointcloud(pointcloud):
    """
    A data augmentation technique that translates the pointcloud randomly.

    Parameters
    ----------
    pointcloud : numpy.ndarray
    
    See Also
    --------
    rotate_pointcloud, jitter_pointcloud
    """

But I have this: image

In my conf.py I use:

extensions = [
    'sphinx.ext.duration',
    'sphinx.ext.doctest',
    'sphinx.ext.autodoc',
    'sphinx.ext.autosummary',
    'numpydoc',
    ]
html_theme = 'furo'

What am I doing wrong? Is it because of the theme? Is there an easy fix?

Solution

  • Note: The issue has been fixed in Furo 2022.1.2.

    It's definitely the theme. Probably an oversight, or even a bug, as Furo shouldn't change capitalization of identifiers and types in the API documentation. But it does, here, by applying the CSS property text-transform: uppercase.

    You can override it with a custom style. In your docs folder, create a subfolder style, and in it a file custom.css with this content:

    dl.py .field-list dt {
    text-transform: none;
}

    (With Furo versions released more recently than when this question was asked, you'll have to use none !important; instead of just none;. See the follow-up question as to why.)

    Then add these two lines to Sphinx's configuration file conf.py:

    html_static_path = ['style']
html_css_files   = ['custom.css']

    The rendered output will look something like this:

    screenshot