Sphinx 和Read the Docs
Sphinx
Sphinx 是一个强大的文档生成器，具有许多用于编写技术文档的强大功能，包括：
- 维护一份源文档，生成网页，可打印的PDF，用于电子阅读器（ePub）的文档等支持 * reStructuredText 或 Markdown 编写文档
- 被广泛使用的代码文档系统
- 代码示例语法高亮
- 活跃的官方和第三方扩展生态
Read the Docs
Read the Docs提供自动构建，版本控制和在线托管，来简化软件文档的发布和管理。它使用Sphinx生成html静态页面，通过github账户授权，在本地项目push到Github(gitee、gitlab)仓库时，自动完成文档的生成和在线更新
两者关系
Sphinx是一个独立的文档生成工具，可以支持不同的主题，而Read the Docs是一个免费的在线文档托管平台，他通过Github(gitee、gitlab)连接代码库，发布及更新sphinx生成的文档
安装
安装Sphinx
基础服务安装
yum -y install git make python3 python3-pip安装最新版本的sphinx
pip3 install sphinx安装相关插件
- 安装autobuild工具
pip3 install sphinx-autobuild - Read the Docs 主题
pip3 install sphinx_rtd_theme - sphinx Markdown扩展
pip3 install recommonmark pip3 install sphinx_markdown_tables快速开始
创建项目
在你所在项目中创建文件夹docs(后续所有操作都在该文件夹内)。执行
sphinx-quickstartWelcome to the Sphinx 5.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]:
首先，询问你是否要创建独立的源文件和构建目录。实际上对应两种目录结构，一种是在根路径下创建“_build”目录，另一种是在根路径下创建“source”和“build”两个独立的目录，前者用于存放文档资源，后者用于保存构建生成的各种文件。根据个人喜好选择即可，比如我更倾向于独立目录，因此输入 `y`。接着，需要输入项目名称、作者信息、项目版本。
The project name will occur in several places in the built documentation.
> Project name: project
> Author name(s): xiaom
> Project release []: v1然后，可以设置项目的语言，我们这里选择简体中文。
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 /root/docs/source/conf.py.
Creating file /root/docs/source/index.rst.
Creating file /root/docs/Makefile.
Creating file /root/docs/make.bat.
Finished: An initial directory structure has been created.
You should now populate your master file /root/docs/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 linkche项目创建完成，目录结构如下：
[root@tem-213 docs]# tree
.
├── build
├── make.bat
├── Makefile
└── source
├── conf.py
├── index.rst
├── _static
└── _templates
4 directories, 4 filesMakefile：可以看作是一个包含指令的文件，在使用 make 命令时，可以使用这些指令来构建文档输出。build：生成的文件的输出目录。make.bat：Windows 用命令行。_static：静态文件目录，比如图片等。_templates：模板目录。conf.py：存放 Sphinx 的配置，包括在 sphinx-quickstart 时选中的那些值，可以自行定义其他的值。index.rst：文档项目起始文件。
此时我们在docs目录下执行 make html，就会在build/html目录生成Html相关的文件
也可以借助sphinx-autobuild工具启动HTTP服务
sphinx-autobuild --port 8000 --host 0.0.0.0 source build/html &--port指定启动的端口号--host指定host信息
在浏览器输入http://host:8000,即可访问文档
修改主题
打开 conf.py 文件，找到 html_theme 字段，修改为
sphinx_rtd_theme主题html_theme = 'sphinx_rtd_theme'
实践操作
index.rst语法
这里主要分析
index.rst的内容[root@tem-213 docs]# cat source/index.rst .. project documentation master file, created by sphinx-quickstart on Wed Jun 8 15:08:15 2022. You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive.
Welcome to project's documentation!
.. toctree::
:maxdepth: 2
:caption: Contents:
Indices and tables
- :ref:
genindex - :ref:
modindex - :ref:
search - 第1-4行由
..+ 空格开头，属于多行评论（类似于注释），不会显示到网页上。 - 第6-7行是标题，reST 的标题需要被双下划线（或单下划线）包裹，并且符号的长度不能小于文本的长度。
- 第9-11行是文档目录树结构的描述，
.. toctree::声明了一个树状结构（toc 即 Table of Content），:maxdepth: 2表示目录的级数（页面最多显示两级），:caption: Contents: 用于指定标题文本（可以暂时去掉）。 - 第15-20行是索引标题以及该标题下的三个索引和搜索链接
<<项目信息>>
我们进入 source 目录，修改 index.rst 文件，将标题改为“项目信息”，并添加一个 about 页面。
[root@tem-213 docs]# vi source/index.rst .. project documentation master file, created by sphinx-quickstart on Wed Jun 8 15:08:15 2022. You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive.
项目信息
.. toctree::
:maxdepth: 2
:caption: Contents:
about
## 支持Markdown
在`conf.py `配置文件中添加扩展支持
```bash
extensions = [
'recommonmark',
'sphinx_markdown_tables'
]我们为日记添加一级子目录。先在 source/index.rst 中添加路径信息。
[root@tem-213 docs]# cat source/index.rst
.. project documentation master file, created by
sphinx-quickstart on Wed Jun 8 15:08:15 2022.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
项目信息
===================================
.. toctree::
:maxdepth: 2
:caption: 项目信息:
2022/index
about
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`创建目录2022
mkdir source/2022创建index.rst
[root@tem-213 docs]# cat source/2022/index.rst
.. project documentation master file, created by
sphinx-quickstart on Wed Jun 8 15:08:15 2022.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
2022
===================================
.. toctree::
:maxdepth: 2
:caption: Contents:
项目信息
about
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`添加Markdown文件
[root@tem-213 docs]# cat source/2022/项目信息.md
# 标题1
## 标题2
### 标题3
### 标题3
[root@tem-213 docs]# 最后显示效果如下：
