240708-Sphinx常用插件整理

extensions = [
    "sphinx.ext.napoleon",
    "sphinx.ext.autodoc",
    "sphinx.ext.autosummary",
    "sphinx.ext.todo",
    "sphinx.ext.viewcode",
    "sphinx.ext.intersphinx",
    "sphinx.ext.graphviz",
    "sphinxext.rediraffe",  # pip install sphinxext-rediraffe
    "sphinx_design",  # pip install sphinx_design
    "sphinx_copybutton",  # pip install sphinx-copybutton
    "autoapi.extension",
    # custom extentions
    "_extension.gallery_directive",
    "_extension.component_directive",
    # For extension examples and demos
    "myst_parser",  # pip install myst-parser
    "ablog",  # pip install ablog
    "jupyter_sphinx",  # pip install jupyter-sphinx
    "sphinxcontrib.youtube",  # pip install sphinxcontrib-youtube
    "nbsphinx",  # pip install sphinx_togglebutton jupyterlite_sphinx sphinx_favicon sohinx_sitemap linkify-it-py matplotlib pandas plotly xarray ipyleaflet
    "numpydoc",
    "sphinx_togglebutton",
    "jupyterlite_sphinx",
    "sphinx_favicon",
]

下面是这些 Sphinx 插件的作用介绍：

1. sphinx.ext.napoleon：

   • 支持 NumPy 和 Google 风格的 docstrings，方便将代码注释转换为文档。

2. sphinx.ext.autodoc：

   • 自动从注释中生成文档，特别适用于生成 API 文档。

3. sphinx.ext.autosummary：

   • 自动生成摘要页面和文档目录，常与 autodoc 一起使用。

4. sphinx.ext.todo：

   • 支持在文档中添加 TODO 列表和条目，可以选择性地显示或隐藏这些条目。

5. sphinx.ext.viewcode：

   • 在文档中提供源代码的链接，方便查看代码实现。

6. sphinx.ext.intersphinx：

   • 允许文档之间的交叉引用，可以引用其他项目的文档。

7. sphinx.ext.graphviz：

   • 支持 Graphviz 语法，可以在文档中插入和显示图表。

8. sphinxext.rediraffe：

   • 支持 URL 重定向，适用于重构文档结构时保持旧链接可用。

9. sphinx_design：

   • 提供设计组件和样式，可以更好地美化和布局文档内容。

10. sphinx_copybutton：

    • 在代码块旁边添加一个复制按钮，方便用户复制代码。

11. autoapi.extension：

    • 自动从代码中生成 API 文档，类似于 autodoc，但提供更多的配置选项和支持。

12. _extension.gallery_directive：

    • 自定义扩展，通常用于展示图库或图像集合。

13. _extension.component_directive：

    • 自定义扩展，通常用于定义和展示组件。

14. myst_parser：

    • 支持 Markdown 语法，可以在 Sphinx 项目中使用 Markdown 编写文档。

15. ablog：

    • 为 Sphinx 添加博客功能，可以在文档站点中发布博客文章。

16. jupyter_sphinx：

    • 支持在文档中嵌入和运行 Jupyter Notebook 内容。

17. sphinxcontrib.youtube：

    • 支持在文档中嵌入 YouTube 视频。

18. nbsphinx：

    • 支持将 Jupyter Notebooks 转换为 Sphinx 文档。

19. numpydoc：

    • 专门支持 NumPy 风格的 docstrings，有助于标准化文档格式。

20. sphinx_togglebutton：

    • 提供可折叠内容块，用户可以展开和折叠内容。

21. jupyterlite_sphinx：

    • 支持在文档中嵌入 JupyterLite 内容，使得文档中可以包含交互式 Jupyter 环境。

22. sphinx_favicon：

    • 支持在文档中设置自定义 favicon 图标。

这些插件帮助增强和扩展 Sphinx 的功能，使得文档生成更为便捷和多样化。