sphinx - python项目文档构建工具

Sphinx是一个基于Python的文档生成工具，它可以将标记文本转换为各种格式的文档，包括HTML、PDF、EPUB等。Sphinx最初是为Python文档而开发的，但是它也可以用于其他类型的文档，例如API文档、技术文档、用户手册等。

Sphinx的主要特点包括

  • 支持多种标记语言，包括reStructuredText、Markdown等。
  • 支持多种输出格式，包括HTML、PDF、EPUB等。
  • 支持自定义主题和样式，可以根据需要进行定制。
  • 支持自动生成API文档和代码示例。
  • 支持自动生成索引、目录、交叉引用等。

Sphinx的使用方法比较简单，通常包括以下步骤

安装库
1
$ pip install sphinx
初始化文档
1
2
3
# 项目根目录下执行
$ sphinx-quickstart 
# 按照提示输入项目相关信息

运行后在docs目录下生成source(文档源码)和build(用于生成HTML文档)目录和Makefile相关文件(用于支持make html命令)。
source中包含了sphinx的配置文件conf.py以及文档首页index.rst。

*编写文档

在source目录下编写文档，可以使用reStructuredText或Markdown等标记语言。
Sphinx 使用 ReStructuredText (reST) 标记语言来编写文档。ReStructuredText 是一种易读易写的文本格式，用于撰写标记语言，包括文档、报告、幻灯片等。

标题
1
2
3
4
5
标题1  
=======  

标题2  
-------
段落

段落之间使用空行分隔，不需要其他标记。

列表
  1. 有序列表：
1
2
3
1. 项目1  
2. 项目2  
3. 项目3
  1. 无序列表：
1
2
3
- 项目1  
- 项目2  
- 项目3
引用

引用文本使用 > 符号：

1
> 这是一个引用文本。
源代码块

使用 :: 标记来插入源代码块，指定语言（可选）：

1
2
3
.. code-block:: python  

   print("Hello, World!")
链接

文本链接：

1
链接到 [Python 官网](https://www.python.org/)

引用链接：

1
请参考 `更多信息 <link>`_ 。
图片

插入图片：

1
2
.. image:: /path/to/image.png  
   :alt: 图片描述
注解

使用 .. note::、.. warning::、.. attention:: 等指令添加注解和警告：

1
2
3
.. note:: 这是一个注解  

.. warning:: 这是一个警告
表格

使用两个竖线 | 来分隔列，使用等号 - 来分隔标题和内容：

1
2
3
4
5
+----------+-----------+  
| 标题1    | 标题2     |  
+==========+===========+  
| 内容1    | 内容2     |  
+----------+-----------+
交叉引用

引用其它部分的文档内容：

1
参见 `API文档 <api>`_ 。
定义列表

定义术语、名词的解释：

1
2
3
4
5
术语1  
   : 定义1  

术语2  
   : 定义2
区块

使用 .. container:: 指令创建带有自定义样式的区块：

1
2
3
4
.. container::  
   :class: custom-block  

   这是一个自定义的区块
插入目录

通过 .. toctree:: 指令插入文档目录结构：

1
2
3
4
5
.. toctree::  
   :maxdepth: 2  

   chapter1.rst  
   chapter2.rst
生成文档
1
make html
生成模块文档

使用sphinx-apidoc命令可以根据Python模块注释自动生成模块文档。

  1. 修改sphinx配置conf.py，在模块查找路径中添加当前项目根路径。
    在conf.py文件头部添加

    1
    2
    3
    4
    import os  
    import sys  

    sys.path.insert(0, os.path.abspath('..'))

  2. 在 conf.py扩展配置中添加 sphinx.ext.autodoc,和 sphinx.ext.viewcode,

    1
    2
    3
    4
    5
    6
    7
    8
    extensions = [
        'sphinx.ext.autodoc',
        'sphinx.ext.viewcode',
    ]
    '''
    sphinx.ext.autodoc：根据代码注释自动生成模块文档。
    sphinx.ext.viewcode：增加[source]查看源码功能。
    '''

  3. 将某个py模块生成rst文件存放到某目录下

    1
    2
    3
    $ sphinx-apidoc -o <output_dir> <module_path>
    # <output_dir> 是生成的 .rst 文件存放的目录。
    # <module_path> 是要包含在 .rst 文件中的 Python 模块的路径

使用 readthedoc 主题

原生主题白且单调，可以安装使用sphinx_rtd_theme

安装主题
1
$ pip install sphinx-rtd-theme
使用主题

修改sphinx配置conf.py，导入sphinx_rtd_theme，并修改html_theme及html_theme_path配置

1
2
3
import sphinx_rtd_theme
html_theme = "sphinx_rtd_theme"
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
重新make html生成文档

浏览器打开build/html/index.html，效果如下：

多语言文档（文档翻译）

  1. 安装sphinx、sphinx-rtd-theme和多语言翻译工具sphinx_intl
1
$ pip install sphinx sphinx-rtd-theme sphinx_intl
  1. 在sphinx配置conf.py中添加语言及国际化目录配置
1
2
language = 'zh_CN'
locale_dirs = ['locale/']
  1. 提取文本及生成待翻译(中文)文本
1
2
3
$ cd source
$ sphinx-build -b gettext . locale
$ sphinx-intl update -p locale -l zh_CN
  1. 翻译docs/source/locale/zh_CN/LC_MESSAGES中所有的.po文件，其中msgid是原始英文，msgstr是要翻译的对应的中文

  1. 查看文档，将url中的en修改为zh_CN后即可查看中文文档，如下图