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-quickstart

  Welcome to the Sphinx 5.0.1 quickstart utility.

Please enter values for the following settings (just press Enter toaccept 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 files

• Makefile：可以看作是一个包含指令的文件，在使用 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]#

最后显示效果如下：