Sphinx 自动化文档

目录

文章目录

• 目录
• Sphinx
• 入门
• reStructuredText 语法格式
• 标题、列表、正文、要点
• 表格
• 代码块
• 引用其他模块文件
• 引用静态图片

Sphinx

Sphinx 是一个工具，它使得创建一个智能而美丽的文档变得简单。作者是 Georg Brandl，基于 BSD 许可证。起初为写 Python 文档而诞生的 Sphinx，现在已经支持为各种语言生成软件开发文档。Sphinx 使用 reStructuredText 作为编写语言，也可以使用 Markdown+拓展库 的方式进行文档的编写。

官方网站：https://www.sphinx.org.cn/

它具有以下突出特性：

• 输出格式：HTML（包括 Windows 的 HTML 帮助文件）、LaTex（可以打印为 PDF）、epub（流行的电子书格式）、Texinfo、manual pages（man 手册）、plain Text（纯文本）。
• 广泛的交叉引用：语义标记和函数，类，引用，词汇表术语和类似信息的自动链接。
• 分层架构：轻松定义文档树，自动链接到平级，上级和下级。
• 自动索引：一般索引以及特定于语言的模块索引。
• 代码高亮：使用Pygments荧光笔自动突出显示。
• 扩展：自动测试代码片段，包含 Python 模块（API 文档）中的文档字符串等。
• 丰富的拓展：用户在第二个存储库中贡献了 50 多个扩展，其中大多数可以从 PyPI 安装。

入门

• 安装：Sphinx 依赖 Python2.4 及以上版本。

pip3 install -U sphinx

• 创建文档项目：在项目的根目录下创建 doc 子目录，并执行文档创建指令，期间你需要交互输入一些配置。

$ sphinx-quickstart 

mickeyfan$ sphinx-quickstart
欢迎使用 Sphinx 2.4.3 快速配置工具。

请输入接下来各项设置的值（如果方括号中指定了默认值，直接
按回车即可使用默认值）。

已选择根路径：.

布置用于保存 Sphinx 输出的构建目录，有两种选择。
一是在根路径下创建“_build”目录，二是在根路径下创建“source”
和“build”两个独立的目录。
> 独立的源文件和构建目录（y/n） [n]: y

项目名称会出现在文档的许多地方。
> 项目名称: 5G Provider
> 作者名称: fanguiju
> 项目发行版本 []: v1.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.
> 项目语种 [en]: zh_CN

创建文件 ./source/conf.py。
创建文件 ./source/index.rst。
创建文件 ./Makefile。
创建文件 ./make.bat。

完成：已创建初始目录结构。

你现在可以填写主文档文件 ./source/index.rst 并创建其他文档源文件了。 用 Makefile 构建文档，像这样：
 make builder
此处的“builder”是支持的构建器名，比如 html、latex 或 linkcheck。

• 配置：创建好文档项目之后，可以看见一下文件或子目录：

  • Makefile：在使用 make 命令时，可以使用这些指令（e.g. sphinx-build）来构建文档输出。
  • _build：这是触发特定输出后用来存放所生成的文件的目录。
  • _static：所有不属于源代码（e.g. 图片）一部分的文件均存放于此处，稍后会在构建目录中将它们链接在一起。
  • conf.py：用于存放 Sphinx 的配置值，包括在终端执行 sphinx-quickstart时选中的那些值。
  • index.rst：文档项目的 root 目录。如果将文档划分为其他文件，该目录会连接这些文件。

• 编写文档：在 index.rst 文件中的主标题之后，有一个内容清单，其中包括 toctree 声明，它将所有文档链接都汇集到 Index。例如：

# 我们想将一个新文件添加到文档中，并打算将其命名为 example.rst。

Contents:

.. toctree::
   :maxdepth: 2

   example

注：example.rst 的内容如下

This is a Title
===============
That has a paragraph about a main subject and is set when the '='
is at least the same length of the title itself.

Subject Subtitle
----------------
Subtitles are set with '-' and are required to have the same length 
of the subtitle itself, just like titles.

Lists can be unnumbered like:

 * Item Foo
 * Item Bar

Or automatically numbered:

 #. Item 1
 #. Item 2

Inline Markup
-------------
Words can have *emphasis in italics* or be **bold** and you can define
code samples with back quotes, like when you talk about a command: ``sudo`` 
gives you super user powers! 

• 生成文档：运行 make 命运，并将 HTML 指定为输出格式。可直接将该输出用作网站，因为它包含了生成的所有内容，包括 JavaScript 和 CSS 文件。

$ make html

docs run-test: commands[0] | sphinx-build -W -b html doc/source doc/build/html
正在运行 Sphinx v2.4.3
正在加载翻译 [zh_CN]... 完成
制作输出目录... 完成
构建 [mo]： 0 个 po 文件的目标文件已过期
构建 [html]： 1 个源文件的目标文件已过期
更新环境: [新配置] 已添加 1，0 已更改，0 已移除
阅读源... [100%] index

查找当前已过期的文件... 没有找到
pickling环境... 完成
检查一致性... 完成
准备文件... 完成
写入输出... [100%] index

generating indices...  genindex完成
writing additional pages...  search完成
复制静态文件... ... 完成
copying extra files... 完成
dumping search index in Chinese (code: zh)... 完成
dumping object inventory... 完成
构建 成功.

HTML 页面保存在 doc/build/html 目录。

• 生成静态网页：随着我们完成前面的操作，从两个文件中生成 HTML 之后，我们就拥有一个完整的静态页面网站。使用浏览器访问 build/html 目录下的 index.html 文件

• 添加图片等静态文件：只要将静态文件放置 _static 目录（Sphinx 在创建文档布局时创建了该目录）中，就可以轻松地对其进行引用。。example.rst 的静态清单如下：

.. image:: _static/system_activity.jpg

• 修改皮肤：sphinx 默认提供了好多可选的皮肤，我们可以通过修改 conf.py 调整，比如：

html_theme = "classic"

• 使用 sphinx_rtd_theme 皮肤：
  • 安装

pip3 install sphinx_rtd_theme

- 配置

# conf.py

html_theme = 'sphinx_rtd_theme'

- 重新构建

make html

reStructuredText 语法格式

标题、列表、正文、要点

This is a Title
===============
That has a paragraph about a main subject and is set when the '='
is at least the same length of the title itself.

Subject Subtitle
----------------
Subtitles are set with '-' and are required to have the same length 
of the subtitle itself, just like titles.

Lists can be unnumbered like:

 * Item Foo
 * Item Bar

Or automatically numbered:

 #. Item 1
 #. Item 2

Inline Markup
-------------
Words can have *emphasis in italics* or be **bold** and you can define
code samples with back quotes, like when you talk about a command: ``sudo`` 
gives you super user powers!

表格

.. csv-table::
    :header:参数,类型,含义
    :widths:2,2,5

    test1,String,这里是测试的第一行
    test2,int,这里是测试的第二行

代码块

.. code-block:: xml

    public void test(){
        throws new Exception("this is a test");
    }

引用其他模块文件

.. toctree::
    :macdepth: 3

    module one
    module two

点击跳转

调用 :ref:`点击这里跳转<file.key>`

引用静态图片

.. image:: _static/system_activity.jpg