stsci-rtd-theme

这是一个由空间望远镜科学研究所（STScI）维护的包的Sphinx主题。

此主题继承自sphinx-rtd-theme；然而，CSS样式已修改，以便在多种平台和浏览器上更容易阅读。

安装

您可以通过安装来自PyPI的最新版本来将此主题应用于当前的文档

pip install stsci-rtd-theme

如果您需要最新版本的master分支，可以直接从GitHub安装

pip install https://github.com/spacetelescope/stsci_rtd_theme.git

如果您想修改源代码，应该在本地克隆存储库并安装可编辑的（-e）

git clone https://github.com/spacetelescope/stsci_rtd_theme.git
cd stsci_rtd_theme
pip install -e .

Sphinx配置

如果您还没有创建Sphinx文档，可以使用sphinx-quickstart开始sphinx，并按照引导步骤进行。完成后，将这些行添加到您的docs/conf.py文件中

# docs/conf.py

import stsci_rtd_theme

html_theme = 'stsci_rtd_theme'
html_theme_path = [stsci_rtd_theme.get_html_theme_path()]

ReadTheDocs配置

将以下行添加到您的docs/conf.py文件中

# docs/conf.py

import sphinx
import os
from packaging.version import Version


def setup(app):
    app.add_css_file("stsci.css")


extensions = [
    ...
]

on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
if on_rtd:
    extensions.append('sphinx.ext.mathjax')
elif Version(sphinx.__version__) < Version('1.4'):
    extensions.append('sphinx.ext.pngmath')
else:
    extensions.append('sphinx.ext.imgmath')

最后，确保将stsci-rtd-theme包含在docs附加中，或者可以选择将stsci-rtd-theme添加到rtd-requirements.txt文件中。然后，在.readthedocs.yaml中包含以下内容（根据用于定义stsci-rtd-theme依赖关系的方法之一）

# .readthedocs.yaml
install:
  - method: pip
    path: .
    extra_requirements:
      - docs

# .readthedocs.yaml
install:
  - requirements: .rtd-requirements.txt
  - method: pip
    path: .