目录
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 目录。如果将文档划分为其他文件,该目录会连接这些文件。
- Makefile:在使用
-
编写文档:在 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
相关阅读: