适用于Qiskit及其生态系统项目的Sphinx主题
项目描述
qiskit-sphinx-theme
Qiskit生态系统文档的Sphinx主题。
警告：新主题迁移
在qiskit-sphinx-theme 1.14中，我们用基于Furo的新qiskit-ecosystem主题替换了旧的基于Pytorch的qiskit_sphinx_theme主题。在qiskit-sphinx-theme 2.0中删除了旧主题。
有关迁移说明，请参阅 从旧Pytorch主题迁移到新主题
概述
此存储库托管三件事
qiskit-ecosystem主题（位于src/文件夹中）- 示例文档（位于
example_docs/文件夹中） - Qiskit 文档指南（位于
docs_guide/文件夹中）
qiskit-ecosystem 主题被 Qiskit 生态系统中的项目使用。Qiskit 生态系统。
示例文档是一个用于测试 Qiskit Sphinx 主题的最小化 Sphinx 项目。每次 pull request 都会触发 GitHub 工作流，构建示例文档以确保更改不会引入意外的更改。
Qiskit 文档指南托管了说明、指南和良好的文档实践建议。其目的是帮助 Qiskit 维护者改进其项目的文档。指南托管在以下网址：[https://qisk.it/docs-guide](https://qisk.it/docs-guide)。
安装
此软件包可通过 PyPI 使用
pip install qiskit-sphinx-theme
然后，通过更新 conf.py 来设置主题
- 设置
html_theme = "qiskit-ecosystem" - 将
"qiskit_sphinx_theme"添加到extensions
您还可能在 conf.py 中设置 html_title。这会使左侧边栏的名称更加有用和简洁，同时在浏览器中包含页面标题。大多数项目都希望将其用于他们的 conf.py
# Sphinx expects you to set these already.
project = "My Project"
release = "4.12"
# This sets the title to e.g. `My Project 4.12`.
html_title = f"{project} {release}"
启用翻译
有关如何使用不同语言构建文档的说明，请参阅 Sphinx 国际化指南
一旦您有了翻译后的文档，您需要开始将文档部署到 <project-prefix>/locale/<locale-code>/，例如 https://qiskit-community.github.io/qiskit-finance/locale/de_DE/index.html。
最后，更新您的 conf.py
- 确保
qiskit_sphinx_theme在extensions设置中。 - 将选项
translations_list设置为包含区域代码和语言名称的成对列表，例如[..., ("de_DE", "German")]。 - 将选项
docs_url_prefix设置为您项目的 URL 前缀，如qiskit-finance。
例如
extensions = [
...,
"qiskit_sphinx_theme",
]
translations_list = [
('en', 'English'),
('bn_BN', 'Bengali'),
('fr_FR', 'French'),
('de_DE', 'German'),
]
docs_url_prefix = "qiskit-finance"
启用早期版本
此功能允许您在左侧边栏中链接到文档的早期版本。
首先，将文档部署到 <project-prefix>/stable/<version>/，例如 https://qiskit-community.github.io/qiskit-experiments/stable/0.5/index.html。请参阅 https://github.com/qiskit-community/qiskit-experiments/blob/7a0924c24549ab4f38819a86c0ac49214d819ba2/.github/workflows/docs_stable.yml#L25-L38 以获取示例。
然后，更新您的 conf.py
- 确保
qiskit_sphinx_theme在extensions设置中。 - 向
html_context选项添加一个包含先前版本的version_list条目，例如["0.4", "0.5"]。- 必须使用上述
stable/<version>URL 方案部署这些版本。 - 您可以手动设置此值，或者某些项目编写 Sphinx 扩展以动态计算该值。
- 您应只在此列表中放置先前版本，不要放置当前版本。
- 必须使用上述
- 将选项
docs_url_prefix设置为您项目的 URL 前缀，如qiskit-experiments。
例如
extensions = [
...,
"qiskit_sphinx_theme",
]
html_context = {
"version_list": ["0.4", "0.5"],
}
docs_url_prefix = "qiskit-experiments"
使用自定义 RST 指令
qiskit_sphinx_theme 扩展为您定义了以下自定义指令，您可以在 RST 中使用它们。有关如何使用它们的示例，请参阅 example_docs/docs/sphinx_guide/custom_directives.rst。
qiskit-cardqiskit-call-to-action-item和qiskit-call-to-action-grid
添加自定义标志
您可以通过将标志文件（SVG 或 PNG）添加到您的 conf.py 的同级位置来添加自定义标志，例如 docs/logo.svg。然后，将 conf.py 中的 html_logo 设置为文件名，例如 html_logo = "logo.png"。
当使用自定义标志时，您可能希望通过在 conf.py 中的 html_theme_options 中设置 sidebar_hide_name 来禁用侧边栏中的项目名称
html_theme_options = {
"sidebar_hide_name": True,
}
Qiskit 生态系统成员
如果您的项目是 Qiskit 生态系统 的成员，我们鼓励您设置以下配置，以便左侧边栏提到您的项目在生态系统中。
更新 conf.py
html_theme_options = {
"sidebar_qiskit_ecosystem_member": True,
}
非生态系统成员不应设置此选项。
提示：建议的网站结构
为了在不同Qiskit生态系统包中保持UX/UI的一致性，建议您使用以下结构来设置您的侧边栏，这可以在您的index.rst的toctree中设置
.. toctree::
:hidden:
Documentation Home <index>
Getting Started <getting_started>
Tutorials <tutorials/index>
How-to Guides <how_to/index>
API Reference <apidocs/index>
Explanations <explanations/index>
Release Notes <release_notes>
GitHub <https://github.com/your-repo>
toctree中的每个条目都对应一个单独的.rst文件，可以使用内部链接或外部链接。外部链接旁边将显示一个“新标签页”图标。
下载文件
下载您平台上的文件。如果您不确定选择哪个，请了解有关安装包的更多信息。
源分布
构建分布
qiskit_sphinx_theme-2.0.0.tar.gz的哈希
| 算法 | 哈希摘要 | |
|---|---|---|
| SHA256 | 3bd305a27a96aff7bab533ec09a546ad3c5c6171f308db474c22c8fb1dd5b342 |
|
| MD5 | 23ede84102a28db0d05ae8b1aa31c138 |
|
| BLAKE2b-256 | ba55b9900b1751e9fc9aacd728304f23f1bba7c62cf35d0aef2bebd4e9e3d45d |
qiskit_sphinx_theme-2.0.0-py3-none-any.whl 的哈希值
| 算法 | 哈希摘要 | |
|---|---|---|
| SHA256 | 30e564c7197fc12754132b37696d86d80221165b471c46bf74b3c0238dbb8956 |
|
| MD5 | 8f2f4100265a141adb427b9ff58392fd |
|
| BLAKE2b-256 | f21d5da0201ffb2ac4087bba0b34a2cdec4f976d3d4dd5c24be571a286c0d177 |