编写文档
构建文档
科学 Python 软件文档可以用 Markdown 语法编写，如下所示
# My nifty title
- list
- of
- items
Some **bold** or _italicized_ text!
```python
# A code block
1 + 1
```
然后将此文档“源代码”构建成 HTML 或 PDF 等格式，以显示给用户。
有各种工具可以做到这一点。在本指南中，我们将介绍科学 Python 社区中主流的一种方法：使用 Sphinx 文档生成器和 MyST 插件。有关 Markdown 语法的一般信息以及 MyST 的 Markdown 变体，请参阅 MyST 文档。
我们将从一个非常基本的模板开始。首先在您的项目中创建一个 docs/ 目录（即在 src/ 旁边）。
mkdir docs
在此目录中，我们将在 docs/conf.py 中创建一个最小的 Sphinx 配置文件。
# content of docs/conf.py
project = "example"
extensions = ["myst_parser"]
source_suffix = [".rst", ".md"]
并且，在 docs/index.md 中，我们将为我们的文档创建一个最小的首页。
# Example documentation
Hello world!
您现在应该拥有类似以下内容。
example/
├── docs/
│ ├── conf.py
│ ├── index.md
(...)
要从此源代码构建 HTML，请安装 sphinx 和 MyST Markdown 解析器
pip install sphinx myst-parser
然后运行 sphinx-build，将其指向您的源文件目录和用于写入渲染（HTML）输出文件的目标目录。
sphinx-build docs/ docs/build/
您应该会看到一些以 build succeeded. 结尾的日志消息。这创建了目录 docs/build。在您的网络浏览器中打开 docs/build/index.html 以查看文档。
MyST Markdown 的基本功能
有关包括以下主题在内的内容，我们建议您参阅 MyST 文档
- 排版
- 表格
- 图像和图形
- 交叉引用
- 数学和方程式
- 包含来自其他文件的内容
结构
我们从这个结构开始，只有一个文档页面。
example/
├── docs/
│ ├── conf.py
│ ├── index.md
(...)
假设我们在子目录中添加了一些教程页面。
example/
├── docs/
│ ├── conf.py
│ ├── index.md
│ └── tutorials/
│ ├── installation.md
│ ├── first-steps.md
│ └── real-application.md
(...)
我们可以使用 MyST Markdown 的 {toctree} 指令从首页链接到它们。
```{toctree}
tutorials/installation.md
tutorials/first-steps.md
tutorials/real-application.md
```
有关更多详细信息，请参阅 MyST 文档页面上的 组织内容。
自动生成参考文档
参考文档提供了 API 的全面文档：代码库中每个公共对象的全部输入和输出。这不应该手动编写；这将很乏味，并且很可能出现人为错误或随着时间的推移而不同步。
MyST 建议使用 sphinx-autodoc2。但是，我们目前建议使用内置的 sphinx autodoc 和 autosummary 扩展，因为它们与按照 numpydoc 标准编写的文档字符串很好地互操作。要调用它们，我们需要使用另一种语法（reST）。幸运的是，您可以简单地复制/粘贴这些示例。
在 docs/conf.py 中，添加到扩展列表中。
extensions = [
# whatever you already have in here...
"sphinx.ext.autodoc",
"sphinx.ext.autosummary",
"sphinx.ext.napoleon",
]
（请注意，这些扩展随 sphinx 提供，因此无需安装任何其他内容。）
您可以记录单个对象（例如函数），在页面上内联显示
```{eval-rst}
.. autofunction:: example.refraction.snell
:noindex:
:toctree: generated
```
或者您可以生成一个表格，其中包含指向每个对象的文档的链接。
```{eval-rst}
.. autosummary::
:nosignatures:
:toctree: generated
example.refraction.snell
```
有关如何将其集成到包中以及 nox 设置的更多信息，请参阅 指南。