API 文档中的 Furo Sphinx 主题大写过多

Question

我是 Sphinx 文档的初学者。我想制作 numpy 风格的文档。因此，我使用了 numpydoc 扩展。 Numpy 使用 pydata 主题，但我选择了 furo。我知道在外观上会有一些差异，但我希望我的页面至少具有与 numpy 相同的格式，尽管我得到了参数名称和类型大写。说明未大写。

我的文档字符串：

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

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

但是我有这个：

在我的 conf.py 中，我使用：

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

我做错了什么？是因为主题吗？有简单的解决方法吗？

Answer 1

注意：该问题已在 Furo 2022.1.2 中修复。

绝对是主题。可能是疏忽，甚至是错误，因为 Furo 不应更改 API 文档中标识符和类型的大写。但确实如此，here，通过应用 CSS 属性 text-transform: uppercase.

您可以使用自定义样式覆盖它。在您的 docs 文件夹中，创建一个子文件夹 style，并在其中创建一个包含以下内容的文件 custom.css：

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

（随着 Furo 版本的发布比提出这个问题时更新，您必须使用 none !important; 而不是 none;。请参阅 follow-up question 了解原因。 )

然后在Sphinx的配置文件中加入这两行conf.py:

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

呈现的输出将如下所示：

API 文档中的 Furo Sphinx 主题大写过多

Furo Sphinx theme uppercases too much in API documentation

python

themes

python-sphinx

documentation-generation