开发者工作流程

从文档字符串生成API参考文档

如果你正在使用Jupyter Book来编写包文档，使用Sphinx autodoc扩展可以自动生成API参考文档，从而节省时间。为此，首先需要在_config.yaml中添加autodoc扩展：

sphinx:
  extra_extensions:
  - 'sphinx.ext.autodoc'

然后，你可以选择使用MyST eval_rst指令，或者为API参考页创建一个单独的.rst文件。这个文件可以命名为任何名称（例如api.rst），只要它在_toc.yml中被引用，并且内容应类似于：

API Reference
=============

.. automodule:: my_project.my_module
    :members:

下次构建你的书籍时，autodoc将从该模块中提取所有文档字符串，并为所有这些字符串创建一个单独的文档页面。如果你想获得更多控制权并在右侧边栏中显示目录，可以逐个添加标题和函数：

API Reference
=============

Func one
--------
.. autofunction:: my_project.my_module.func_one

Func two
--------
.. autofunction:: my_project.my_module.func_two

如果你的文档字符串遵循NumPy或Google的约定，可以添加Napoleon扩展来正确解析和渲染它们。另一个有用的扩展可以为每个函数插入源代码链接，并且可以选择将函数名称缩短为仅基名：

sphinx:
  extra_extensions:
  - 'sphinx.ext.autodoc'
  - 'sphinx.ext.napoleon'
  - 'sphinx.ext.viewcode'
  config:
    add_module_names: False

如果你的项目结构更为复杂，并希望递归提取所有子模块及其函数的文档字符串，可以使用Autosummary扩展，并结合recursive:选项（自Sphinx 3.1起）：

sphinx:
  extra_extensions:
  - 'sphinx.ext.autodoc'
  - 'sphinx.ext.autosummary'
  config:
    autosummary_generate: True

你的api.rst文件现在应如下所示：

API documentation
=================

.. autosummary::
   :toctree: _autosummary
   :recursive:

   my_module

要从摘要页面插入可点击的链接指向每个函数的文档字符串，目前需要修改默认模板，并且默认情况下，链接至少在Sphinx 4之前不会启用。另一种递归生成可点击函数链接的选项是AutoAPI扩展，它可以通过pip安装，并且相对于上述方法需要较少的定制。