使用Sphinx生成项目文档

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

Sphinx的主要特点包括：

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

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

1. 安装Sphinx
   可以使用pip命令安装Sphinx：

pip install sphinx

2. 初始化项目
   使用sphinx-quickstart命令初始化Sphinx项目，该命令会生成一个包含配置文件和目录结构的项目（建议在项目中新建一个docs目录，在docs目录下执行该命令）：

mkdir docs && cd docs
sphinx-quickstart

按照提示输入相关信息

Welcome to the Sphinx 7.0.1 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  # 是否分离文档源码和生成的HTML

The project name will occur in several places in the built documentation.
> Project name: python-yapi    # 项目名称
> Author name(s): Han Zhichao  # 作者名称
> Project release []: 0.1.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]: en   #  语言

Creating file /Users/superhin/Projects/python-yapi/docs/source/conf.py.
Creating file /Users/superhin/Projects/python-yapi/docs/source/index.rst.
Creating file /Users/superhin/Projects/python-yapi/docs/Makefile.
Creating file /Users/superhin/Projects/python-yapi/docs/make.bat.

Finished: An initial directory structure has been created.

You should now populate your master file /Users/superhin/Projects/试验/argparse_demo/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.

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

3. 编写文档
   在source目录下编写文档，可以使用reStructuredText或Markdown等标记语言。

reStructuredText格式参考：https://www.sphinx-doc.org/zh_CN/master/usage/restructuredtext/basics.html

4. 生成文档
   使用make命令生成文档，例如：

make html

该命令会生成HTML格式的文档，保存在build/html目录下。

Sphinx还提供了丰富的配置选项和插件，可以根据需要进行定制。你可以参考Sphinx官方文档，了解更多详细信息和用法示例。

生成模块文档

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

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

import os
import sys
sys.path.insert(0, os.path.abspath('../..'))  # 将项目根目录添加到模块查找路径中去

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

extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.viewcode',
]

• sphinx.ext.autodoc：根据代码注释自动生成模块文档。
• sphinx.ext.viewcode：增加[source]查看源码功能。

2. 在命令行进入docs/目录，使用sphinx-apidoc命令生成python_yapi模块文档到source目录

cd docs
sphinx-apidoc -o source ../python_yapi

执行后在source目录下生成modules.rst和python_yapi.rst, 如下图：

在index.rst内容列表中添加modules

在docs目录，命令行使用make html生成文档，使用浏览器打开build/html目录的index.html

使用 readthedoc 主题

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

1. 安装主题

pip install sphinx-rtd-theme

2. 使用主题
   修改sphinx配置conf.py，导入sphinx_rtd_theme，并修改html_theme及html_theme_path配置

import sphinx_rtd_theme
html_theme = "sphinx_rtd_theme"
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]

3. 重新make html生成文档
   浏览器打开build/html/index.html，效果如下：

文档托管-发布文档到Readthedocs

1. 在项目根目录下新建文件.readthedocs.yaml，指定sphinx配置文件路径，并上传代码到GitHub仓库。

version: 2
build:
  os: ubuntu-22.04
  tools:
    python: "3.9"
sphinx:
   configuration: docs/source/conf.py  # sphinx配置文件路径

2. 打开https://readthedocs.org/ ,使用Github登录（或注册登录）
   导入当前项目（或手动导入项目）

点击Build version按钮，成功后点击阅读文档即可查看发布后的文档。

多语言文档（文档翻译）

1. 在readthedocs上想要生成支持多语言文档，需要另外新建一个Github项目，如
   python-yapi-docs-zh_CN,
2. 拷贝上一个项目docs及.readthedocs.yaml到当前项目

3. 安装sphinx、sphinx-rtd-theme和多语言翻译工具sphinx_intl

pip install sphinx sphinx-rtd-theme sphinx_intl

4. 在sphinx配置conf.py中添加语言及国际化目录配置

language = 'zh_CN'
locale_dirs = ['locale/']

5. 提取文本及生成待翻译(中文)文本

cd docs/source
sphinx-build -b gettext . locale
sphinx-intl update -p locale -l zh_CN
cd ..

6. 手动翻译docs/source/locale/zh_CN/LC_MESSAGES中所有的.po文件，其中msgid是原始英文，msgstr是要翻译的对应的中文，如下图：

注意：不翻译locale目录下的.po文件。

7. 在docs目录下使用make html并查看build/html/index.html
   效果如下：

8. 上传到Github并在readthedocs中导入项目，并设置其语言为Simplified Chinese，如下图：

9. 在主项目中添加翻译和子项目

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

参考：readthedocs(RTD)托管持多语言文档