开源文档生成工具Sphinx

在学习Python包的时候经常看到使用Sphinx说明文档，不管是形式还是样式看起来都非常的优秀。今天就一起学习下如何自己也能使用Sphinx生成文档。

Sphinx简介

Sphinx是一个强大的文档生成工具，专为编写技术文档而设计，尤其在Python社区中非常流行。它最初是为了创建Python语言的官方文档而开发的，但现在已经广泛应用于许多其他项目的文档编写中。以下是关于Sphinx的一些关键特性和信息：

主要特性

• 易于使用：Sphinx使用reStructuredText作为标记语言，这种语言易于学习和使用，同时提供了丰富的格式化选项。
• 多种输出格式：支持生成多种格式的文档，包括HTML、PDF、EPUB和纯文本等。
• 可扩展性：通过插件和扩展，可以添加各种自定义功能，如搜索、索引和语法高亮等。
• 自动生成API文档：对于Python项目，Sphinx可以直接从源代码中自动生成API文档。
• 国际化支持：支持文档的国际化和本地化，使得创建多语言文档变得简单。

使用流程

• 安装：通过pip安装Sphinx。
• 设置项目：使用sphinx-quickstart 创建一个新的文档项目，该命令将生成必要的配置文件和文件结构。
• 编写文档：在项目中使用reStructuredText编写文档。
• 构建文档：使用Sphinx命令行工具构建文档，生成最终的输出。

集成和应用

• Sphinx可以与各种代码仓库和文档托管服务（如ReadtheDocs）集成，实现文档的自动构建和更新。
• 它广泛应用于软件项目的用户手册、API文档、开发者指南等领域。

适用性

Sphinx特别适合于需要维护大量技术文档的项目，尤其是当文档需要与代码紧密结合时。由于其强大的自动化能力和灵活性，Sphinx成为许多开源项目和企业的首选文档工具。

Sphinx使用教程

安装Sphinx

首先，确保您的系统上安装了Python。然后使用pip安装Sphinx：pip install sphinx

创建文档项目

使用sphinx-quickstart命令创建一个新的Sphinx项目。这将会引导您完成一系列设置步骤，生成必要的配置文件和目录结构。

sphinx-quickstart

按照提示完成项目的基本设置，如项目名称、作者、语言等。

(base) PSE:\helpdoc>sphinx-quickstart
Welcome to the Sphinx 4.4.0 quickstart utility.

Please enter values for the following settings (just press Enter to
accept a default value, if one is given in brackets).

Selected root path: .

You have two options for placing the build directory for Sphinx output.
Either, you use a directory "_build" within the root path, or you separate
"source" and "build" directories within the root path.
> Separate source and build directories (y/n) [n]: y

The project name will occur in several places in the built documentation.
> Project name: SphinxTest
> Author name(s): www.biaodianfu.com
> Project release []: 1.0.0

If the documents are to be written in a language other than English,
you can select a language here by its language code. Sphinx will then
translate text that it generates into that language.

For a list of supported codes, see
https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language.
> Project language [en]: zh_CN

Creating file E:\helpdoc\source\conf.py.
Creating file E:\helpdoc\source\index.rst.
Creating file E:\helpdoc\Makefile.
Creating file E:\helpdoc\make.bat.

Finished: An initial directory structure has been created.

You should now populate your master file E:\helpdoc\source\index.rst and create other documentation
source files. Use the Makefile to build the docs, like so:
   make builder
where "builder" is one of the supported builders, e.g. html, latex or linkcheck.

在Sphinx的配置中，“Project release”指的是您的文档项目当前的发布版本。这个设置在conf.py配置文件中定义，通常与您的软件或文档项目的版本号相对应。这个版本号会在生成的文档中的多个地方显示，例如在文档页脚或页眉。

在Sphinx中，“Project language”指的是您的文档项目所用的主要语言。这个设置是在Sphinx配置文件conf.py中指定的，它决定了文档中的默认语言，影响着文档生成时的语言相关设置，如本地化和翻译。具体语言代码见：Options for internationalization

编写文档

文档是用reStructuredText格式编写的，这是一种类似于Markdown的简单标记语言。您的文档源文件将位于source目录下。

创建或编辑reStructuredText文件（扩展名为.rst），例如index.rst。您可以在这些文件中编写文档内容，并使用Sphinx提供的各种指令和格式化选项。

当然编写文档也支持Markdown，后面会详细介绍。

构建文档

使用以下命令构建文档：

sphinx-build -b html source build/html

这将生成HTML格式的文档，并将其放置在build/html目录下。

在使用Sphinx时，make命令支持生成多种不同格式的文档。以下是一些常见的格式及对应的make命令：

1. HTML

• 命令：make html
• 描述：生成HTML格式的文档，适用于网页发布。

2. PDF (通过LaTeX)

• 命令：make latexpdf
• 描述：首先生成LaTeX文件，然后编译为PDF文档，适用于打印和分发。

3. ePub

• 命令：make epub
• 描述：生成ePub格式的电子书，适合在电子阅读器上阅读。

4. 文本(Text)

• 命令：make text
• 描述：生成纯文本格式的文档。

5. Man Page

• 命令：make man
• 描述：生成 man 手册页，用于 UNIX 和 Linux 系统的帮助手册。

6. LaTeX

• 命令：make latex
• 描述：生成 LaTeX 文件，可以自行编译为 PDF 或其他格式。

7. XML

• 命令：make xml
• 描述：生成 XML 格式的文档。

8. HTML 帮助文件 (HTML Help)

• 命令：make htmlhelp
• 描述：生成 HTML 帮助文件，常用于 Windows 应用程序的帮助文档。

9. Apple Help Book

• 命令：make applehelp
• 描述：生成 Apple Help Book 格式的文档，适用于 macOS 应用程序。

10. gettext

• 命令：make gettext
• 描述：生成用于国际化的 gettext 模板文件。

11. JSON

• 命令：make json
• 描述：生成 JSON 格式的文档。

查看和部署

打开 build/html/index.html 文件以查看生成的文档。如果满意，您可以将这些文件部署到任何 Web 服务器或文档托管服务上。

自定义和扩展

主题

Sphinx 支持多种可自定义的主题。您可以在 conf.py 文件中设置主题。

Sphinx 提供了多种主题，使用户能够根据自己的需求和偏好来定制文档的外观。这些主题不仅影响文档的视觉风格，也可能提供额外的功能，如导航、搜索界面等。

要查看更多可用的主题以及它们的样式，您可以访问Sphinx Themes 页面。此外，还有一个专门的网站Sphinx Themes Gallery，提供了各种主题的预览，帮助用户选择适合自己项目的主题。

扩展

如果需要额外功能，如自动 API 文档生成，您可以安装并配置相应的 Sphinx 扩展。以下是一些流行的 Sphinx 扩展：

1. sphinx.ext.autodoc

• 描述：自动从源代码中提取文档字符串，并将其插入到 Sphinx 文档中。
• 用途：非常适合为 Python 项目生成 API 文档。

2. sphinx.ext.intersphinx

• 描述：允许在不同 Sphinx 文档项目之间进行链接。
• 用途：适用于链接到其他项目的文档，例如 Python 官方文档。

3. sphinx.ext.todo

• 描述：管理文档中的待办事项列表。
• 用途：在开发文档过程中跟踪待完成的任务。

4. sphinx.ext.viewcode

• 描述：在文档中添加链接，指向源代码。
• 用途：非常适用于提供对实现细节的深入查看。

5. sphinx.ext.mathjax

• 描述：使用 MathJax 渲染数学公式。
• 用途：对于包含数学内容的文档非常有用。

6. sphinxcontrib.httpdomain

• 描述：为 HTTP API 添加特殊的指令和角色。
• 用途：适合用来撰写 HTTP API 的文档。

7. sphinxcontrib.plantuml

• 描述：集成 PlantUML，用于生成 UML 图。
• 用途：对于需要在文档中包含 UML 图的项目非常有用。

8. sphinx.ext.doctest

• 描述：使文档可以包含 doctest 测试。
• 用途：适用于编写包含可测试代码示例的文档。

9. myst-parser

• 描述：允许 Sphinx 使用 Markdown 语法编写文档。
• 用途：对于习惯于 Markdown 的用户非常友好。

10. sphinx.ext.napoleon

• 描述：支持 Google 和 NumPy 风格的 docstrings。
• 用途：适合需要这两种风格的 Python 项目。

高级功能

自动生成 API 文档: 如果您的项目是一个 Python 库，Sphinx 可以与工具如 sphinx-apidoc 配合使用，直接从您的 Python 代码生成 API 文档。

国际化: Sphinx 支持文档的国际化，您可以创建多语言版本的文档。

维护和更新

随着项目的发展，定期更新和维护文档是很重要的。确保文档与代码的同步，并及时更新任何变更。

集成其他工具

您可以将 Sphinx 与版本控制系统（如 Git）和文档托管服务（如 Read the Docs）结合使用，实现文档的自动构建和部署。

reStructuredText 简介

reStructuredText（通常简称为 reST）是一种由 Python 社区广泛使用的轻量级标记语言。它是 Docutils 项目的一部分，特别设计用于轻松读写可读的纯文本，同时支持可选的标记来添加样式和结构。reStructuredText 被广泛用于编写文档，尤其是 Python 项目的文档，如在 Sphinx 文档生成器中。

reStructuredText 与 Markdown 对比

reStructuredText（reST）和 Markdown 都是流行的轻量级标记语言，用于编写易于阅读的纯文本文档，并可以转换成丰富的格式，如 HTML。尽管它们在目的上相似，但在语法、功能和使用场景上有一些显著的区别。

语法风格

Markdown：

• 语法更简单、更直观，易于学习，适合初学者。
• 主要关注于简洁性和可读性，适合于快速写作和笔记。
• 使用星号（*）、井号（#）等符号进行格式化。

reStructuredText：

• 语法更为复杂和强大，提供了更多的格式化选项。
• 支持更多的文档结构化元素，如脚注、目录结构、编号引用等。
• 使用不同的符号和构造来表示不同的格式，例如使用下划线来创建链接。

功能和扩展性

Markdown：

• 主要用于基本的文本格式化。
• 对于更复杂的需求，需要依赖于各种扩展，如 GitHub Flavored Markdown（GFM）增加了表格、任务列表等功能。
• 在不同的平台和编辑器中，Markdown 的解析和扩展可能有所不同。

reStructuredText：

• 内置了更丰富的功能，适用于更复杂的文档项目。
• 提供了指令（Directives）和角色（Roles）机制，允许自定义行为和更多控制。

与 Sphinx 文档生成器紧密集成，是编写技术文档和书籍的理想选择。

使用场景

Markdown：

• 广泛用于编写 README 文件、博客、简单的网页和文档。
• 在各种社交媒体、论坛和代码托管平台（如 GitHub、GitLab）中得到广泛应用。

reStructuredText：

• 通常用于编写技术文档，尤其是 Python 社区中的项目文档。
• 与 Sphinx 结合使用，适合创建大型、结构化的文档，如用户手册、技术规范文档。

受众和流行度

Markdown：

• 由于其简单性，被广泛接受和使用，尤其在非技术用户中更受欢迎。
• 很多现代内容管理系统（如 WordPress）和静态站点生成器（如 Jekyll）支持 Markdown。

reStructuredText：

• 更多被技术写作者和开发者使用，尤其是在需要高度结构化和扩展功能的场合。
• 在 Python 社区中尤其流行，作为很多 Python 项目和框架的首选文档格式。

总结来说，Markdown 因其简单性而广受欢迎，适合于快速文档和网页内容的创建。而 reStructuredText 则提供了更高的灵活性和扩展性，更适合于复杂和结构化的文档项目，特别是在技术领域。选择哪一种标记语言取决于您的特定需求、项目类型和个人偏好。

让 Sphinx 支持 Markdown

要使 Sphinx 支持 Markdown，您需要使用扩展，如 recommonmark 或 MyST-Parser。这些扩展允许 Sphinx 识别和正确解析 Markdown 文件。以下是配置 Sphinx 以支持 Markdown 的步骤：

使用 recommonmark

使用 pip 安装 recommonmark 扩展：pip install recommonmark

在 Sphinx 项目的 conf.py 文件中，添加 recommonmark 到扩展列表，并配置 source_suffix：

extensions = [
    'recommonmark',
    # 其他已有扩展
]

# 添加 .md 作为源文件后缀
source_suffix = {
    '.rst': 'restructuredtext',
    '.md': 'markdown',
}

使用 MyST-Parser

使用 pip 安装 MyST-Parser 扩展：pip install myst-parser

在 conf.py 文件中，添加 MyST-Parser 到扩展列表，并配置 source_suffix：

extensions = [
    'myst_parser',
    # 其他已有扩展
]

source_suffix = {
    '.rst': 'restructuredtext',
    '.md': 'markdown',
}

注意事项

• 使用 Markdown 时，您可能无法使用一些特定于 reStructuredText 的功能，如 Sphinx 的某些指令和角色。
• MyST-Parser 提供了一些额外的功能，如允许在 Markdown 中使用一些 Sphinx 特有的功能。

reStructuredText 语法入门

没有什么特殊的内容：建议查看以下文档学习：

• Sphinx reStructuredText 语法入门—MegEngine 1.13.1 文档
• reStructuredText (sourceforge.io)
• reStructureText 语法—sphinx 文档 (sphinx-practise.readthedocs.io)

Visual Studio Code 与 reStructuredText

要在 Visual Studio Code (VSCode) 中支持 reStructuredText (reST 或 RST)，您需要安装一个支持 RST 的扩展。以下是步骤：打开 Visual Studio Code。在 VSCode 中，点击左侧工具栏中的“扩展”图标。或者，您可以使用快捷键 Ctrl+Shift+X（在 Windows 和 Linux 上）或 Cmd+Shift+X（在 macOS 上）。在扩展市场的搜索框中输入“reStructuredText”并按 Enter。您会看到一些与 reStructuredText 相关的扩展。比较受欢迎的一个是由 LeXtudio 提供的“reStructuredText”。点击您选择的扩展旁边的“安装”按钮进行安装。一些扩展可能需要额外的配置，比如设置 Python 解释器或 Sphinx 的路径。通常，安装扩展后，它会指导您完成这些配置步骤。安装并配置好扩展后，您就可以在 VSCode 中开始编写和编辑 reStructuredText 文档了。扩展通常会提供语法高亮、预览、快捷键和其他有用的特性来增强编辑体验。

通过以上步骤，您可以在 Visual Studio Code 中方便地使用 reStructuredText，进一步提升文档编写和编辑的效率。

Sphinx 目录组织

在使用 Sphinx 创建文档时，合理组织目录结构是非常重要的。一个良好的目录结构可以帮助维护文档的清晰度和易用性。以下是一些建议和步骤来组织 Sphinx 文档的目录结构：

• 创建一个根目录。通常，您的文档项目应该有一个根目录，这是所有文档和相关文件的中心位置。例如，您可以创建一个名为 docs 的目录。
• 配置文件。在根目录中，应该有一个名为 py 的配置文件。这个文件包含了 Sphinx 文档的所有配置设置，包括扩展、主题、源文件的路径等。
• 源文件目录。
  • 源文件：您的文档内容通常写在 .rst（reStructuredText）或 .md（Markdown，如果您使用了支持 Markdown 的扩展）文件中。这些文件应该放在一个易于管理的目录中，通常是根目录下的一个名为 source 的子目录。
  • 索引文件：通常，Sphinx 项目有一个主索引文件，通常命名为 rst。它位于源文件目录的根部，并且是文档结构的入口点。
• 静态文件和模板
  • 静态文件：如图像、CSS 样式表或 JavaScript 文件，应该放在一个单独的目录中，例如 source/_static。
  • 模板文件：如果您自定义了 Sphinx 的 HTML 模板，应该将它们放在一个名为 source/_templates 的目录中。
• 子目录和模块化。为了保持文档的可读性和可维护性，您应该根据文档的结构来创建子目录。例如，您可以为每个大的章节或主题创建一个子目录，并在其中放置相关的 .rst 或 .md 文件。
• 构建目录。构建目录是 Sphinx 在构建文档时输出文件的地方。通常，这是一个名为 build 的目录，在根目录中创建。

示例目录结构：

docs/
│
├── source/
│   ├── _static/
│   ├── _templates/
│   ├── conf.py
│   ├── index.rst
│   └── ...(其他 .rst 或 .md 文件)
│
└── build/(由 Sphinx 自动生成)

在 conf.py 文件中，确保正确设置了如 html_static_path 和 html_theme 等选项，以反映您的目录结构。通过遵循以上步骤和建议，您可以创建一个清晰、有序的 Sphinx 文档项目，有助于长期的维护和扩展。

子目录和模块化

在 Sphinx 文档项目中，使用子目录和模块化可以帮助您组织大型文档，使其更加易于管理和维护。下面是如何设置子目录和模块化的详细介绍：

创建子目录

• 规划结构：首先，根据您的文档内容和结构，规划出需要的子目录。通常，每个主要章节或主题可以有一个对应的子目录。
• 创建子目录：在文档源文件目录（通常是 source）中，创建这些子目录。例如，如果您有一个关于“安装指南”的章节，您可以创建一个名为 installation 的子目录。
• 添加文档文件：在相应的子目录中创建或移动 .rst 或 .md 文件。确保每个子目录都有一个主文件，例如 rst，它可以作为该子目录的入口点。

配置子目录

• 更新主索引文件：在主索引文件（通常是 source/index.rst）中，使用 toctree 指令包含子目录的主文件。例如：

.. toctree::
   :maxdepth: 2

   installation/index
   another-section/index

这里 installation/index 和 another-section/index 是指向子目录中的 index.rst 文件的相对路径。

• 设置子目录的索引文件：在每个子目录的 rst 文件中，使用 toctree 指令列出该目录中的所有文档。例如，在 installation/index.rst 中：

安装指南
==========

.. toctree::
   :maxdepth: 1

   installation-step1
   installation-step2

模块化的好处

• 组织清晰：每个章节或主题都有自己的目录，便于管理和查找。
• 易于维护：更改或更新某一部分时，不会影响到其他部分。
• 扩展性好：新增章节或内容时，只需添加新的子目录和文件，而不需大幅修改现有结构。
• 灵活性：可以根据需要轻松调整章节和内容的组织结构。

通过这种方式，您的 Sphinx 文档将更加模块化，每个部分都位于自己的子目录中，从而提高了整体文档的可读性和维护性。

静态资源存储

在 Sphinx 文档项目中，图片和其他静态资源应该存放在一个专门的目录中，通常是在文档源文件目录下的一个名为 _static 的子目录。以下是如何组织和引用图片的详细步骤：

创建静态资源目录

• 创建 _static 目录：在您的 Sphinx 文档源文件目录（通常是 source 目录）中创建一个名为 _static 的子目录。
• 存放图片：将所有需要在文档中使用的图片文件放入此目录。您可以直接将图片放在 _static 目录下，或者在 _static 下创建子目录来更好地组织图片。

配置静态资源路径

更新 conf.py 文件：确保在 conf.py 文件中设置了正确的静态文件路径。通常，这是默认配置，例如：

html_static_path = ['_static']

这告诉 Sphinx 在构建文档时包含 _static 目录中的内容。

在文档中引用图片

使用相对路径：在您的 .rst 或 .md 文件中，可以使用相对路径来引用 _static 目录中的图片。例如，如果您有一张名为 example.png 的图片在 _static 目录中：

在 reStructuredText 中：

.. image:: /_static/example.png
   :alt: 示例图片

在 Markdown 中：

![示例图片](/_static/example.png)

通过这种方式，您可以在 Sphinx 文档中有效地管理和引用图片资源，确保文档的可读性和易于维护性。

其他开源文档工具

除了 Sphinx，还有许多其他优秀的开源文档工具可供选择，各自适用于不同的需求和场景。以下是一些流行的开源文档工具：

Docusaurus

• 特点：由 Facebook 维护，使用 React 编写，支持单页应用程序的文档和博客。
• 适用场景：需要集成现代 web 技术的项目，如 React 应用的文档。
• 网站：Docusaurus 官网

GitBook

• 特点：界面友好，支持 Markdown 和 AsciiDoc，提供文档协作和版本控制。
• 适用场景：团队协作编写文档，尤其是需要版本控制的情况。
• 网站：GitBook 官网

Hugo

• 特点：Go 语言编写的极速静态网站生成器。
• 适用场景：需要快速构建大型静态网站或博客。
• 网站：Hugo 官网

Pelican

• 特点：使用 Python 编写，支持 Markdown 和 reStructuredText。
• 适用场景：适合 Python 开发者或喜欢 Python 生态的用户。
• 网站：Pelican 官网

Jekyll

• 特点：Ruby 编写的静态站点生成器，与 GitHub Pages 无缝集成。
• 适用场景：个人博客、项目文档，尤其是 GitHub 项目。
• 网站：Jekyll 官网

Next.js

• 特点：基于 React 的框架，用于构建静态网站和服务器端渲染的应用程序。
• 适用场景：适合需要 SSR（服务器端渲染）或 SSG（静态站点生成）的高性能应用。
• 网站：Next.js 官网

Docsify

• 特点：Docsify 是一种基于 JavaScript 的文档网站生成器，它能够将 Markdown 文件转换为动态的单页应用程序。Docsify 通过简单的配置和自定义，提供了丰富的特性，例如全文搜索、动态侧边栏、代码高亮等。
• 适用场景：Docsify 适用于构建小型文档网站，例如文档、API 文档、技术博客等。它以简单易用和轻量级为特点，不需要构建过程，可以快速启动和部署，非常适合个人或小型团队使用。
• 网站：Docsify 官网

Vuepress

• 特点：Vuepress 是一个基于 Vue.js 的静态网站生成器，它提供了一个简单的集成体验，在构建文档和目录时可以使用 Vue.js 的强大功能。Vuepress 支持 Markdown 文件编写，提供了许多主题和插件，可以快速地创建漂亮、响应式的静态网站。
• 适用场景：Vuepress 适用于构建各种类型的静态网站，包括文档、博客、企业网站等。Vuepress 的可扩展性和社区支持，使其成为一个非常强大的静态网站生成器，可以满足各种需求。
• 网站：Vuepress 官网

其他推荐：

• Open-source collaborative wiki and documentation software | Docmost

参考链接：

• yoloseem/awesome-sphinxdoc: A curated list of awesome tools for Sphinx Python Documentation Generator (github.com)