插件

由于许多项目在文档中需要特殊功能，Sphinx 允许在构建过程中添加 “插件”，每个插件都可以修改文件处理的几乎任何方面。

本章描述了与 Sphinx 捆绑的插件。关于编写你自己的插件的 API 文档，请参考 为 Sphinx 开发插件。

内置插件

这些插件是内置的，可以通过 extensions 配置值中的各自条目激活：

• sphinx.ext.autodoc – Include documentation from docstrings
  • Directives
  • Configuration
  • Docstring preprocessing
  • Skipping members
• sphinx.ext.autosectionlabel – Allow reference sections using its title
  • Configuration
• sphinx.ext.autosummary – Generate autodoc summaries
  • sphinx-autogen – generate autodoc stub pages
  • Generating stub pages automatically
  • Customizing templates
• sphinx.ext.coverage – Collect doc coverage stats
• sphinx.ext.doctest – Test snippets in the documentation
  • Directives
  • Skipping tests conditionally
  • Configuration
• sphinx.ext.duration – Measure durations of Sphinx processing
• sphinx.ext.extlinks – Markup to shorten external links
• sphinx.ext.githubpages – Publish HTML docs in GitHub Pages
• sphinx.ext.graphviz – Add Graphviz graphs
• sphinx.ext.ifconfig – Include content based on configuration
• sphinx.ext.imgconverter – A reference image converter using Imagemagick
  • Configuration
• sphinx.ext.inheritance_diagram – Include inheritance diagrams
  • Examples
  • Configuration
• sphinx.ext.intersphinx – Link to other projects’ documentation
  • Configuration
  • Showing all links of an Intersphinx mapping file
  • Using Intersphinx with inventory file under Basic Authorization
• sphinx.ext.linkcode – Add external links to source code
  • Configuration
• Math support for HTML outputs in Sphinx
  • sphinx.ext.imgmath – Render math as images
  • sphinx.ext.mathjax – Render math via JavaScript
  • sphinx.ext.jsmath – Render math via JavaScript
• sphinx.ext.napoleon – Support for NumPy and Google style docstrings
  • Overview
    • Getting Started
    • Docstrings
    • Docstring Sections
    • Google vs NumPy
    • Type Annotations
  • Configuration
• sphinx.ext.todo – Support for todo items
  • Configuration
• sphinx.ext.viewcode – Add links to highlighted source code
  • Configuration

三方插件

你可以在 sphinx-contrib 组织中找到几个由用户贡献的插件。如果你想把你的插件加入这个组织，只需按照 github-administration 项目中提供的说明即可。这是可选的，有几个插件托管在其他地方。awesome-sphinxdoc 项目包含一个精心策划的 Sphinx 软件包列表，许多软件包使用 Framework :: Sphinx :: Extension 和 Framework :: Sphinx :: Theme 的分类器，分别用于 Sphinx 的插件和主题。

在哪里放自己的插件？

项目本地的插件应该放在项目的目录结构中。相应地设置 Python 的模块搜索路径，sys.path，以便 Sphinx 能找到它们。例如，如果你的插件 foo.py 位于项目根目录下的 exts 子目录中，就放到 conf.py

import sys, os

sys.path.append(os.path.abspath('exts'))

extensions = ['foo']

你也可以在 sys.path 上的其他地方安装插件，例如在 site-packages 目录下。