python sphinx(文档生成器)入门

简介

Sphinx 是一个 文档生成器 ，您也可以把它看成一种工具，它可以将一组纯文本源文件转换成各种输出格式，并且自动生成交叉引用、索引等。也就是说，如果您的目录包含一堆 reStructuredText 或 Markdown 文档，那么 Sphinx 就能生成一系列HTML文件，PDF文件（通过LaTeX），手册页等。

安装

pip install sphinx

查看是否安装成功

sphinx-build --version

显示对应的版本号即代表安装成功

sphinx-build 5.0.2

Markdown

安装markdown支撑的模块

pip install myst-parser

安装md文档相关主题

pip install sphinx sphinx-autobuild sphinx_rtd_theme recommonmark sphinx-markdown-tables

创建项目

执行如下命令，可以得到一个初始项目

sphinx-quickstart

目录结构如下：



其中

source:文件夹下存放的时配置文件、文档源文件等， 其中最核心的则是conf.py文件和index.rst文件

• conf.py文件是整个项目的配置文件，可以配置插件、主题、项目名称、中英文等
• index.rst文件是整个项目的目录结构，相当于是主目录的意思
  
  build:文件夹下存放的是编译后产生的文件
  
  make.bat:编译所需脚本

md文档转换

设置插件

在conf.py文件中设置extensions字段添加md文档处理

extensions = ["recommonmark"]

新建md文件

下面在source文件夹下新建一个子文件夹叫test, 里面存放md文档相关数据，此处新建一个test.md文档，内容如下:

## 简介
## 测试图片

![avatar](../images/test/test.gif)
![avatar](../images/test2/test.gif)
![avatar](../images/test2/test.jpg)

在主目录中添加md文件目录

在 index.rst中修改如下：

.. toctree::
   :maxdepth: 2

   test/test

编译

在项目根目录下执行如下命令转为html

# 需要注意windows是bat文件
make html

sphinx-build -b html sourcedir builddir
此处就是
sphinx-build -b html source build

生成html文件

所有生成的文件都会存放在build路径下，会有两个文件夹，一个是doctrees,还有一个是html,

html相关会存放在html目录下。如下

注意事项

1.关于图片的引用，sphinx会自动将图片文件移动到_images文件夹下，不同文件夹下的图片都会移动到这个文件夹下，图片名称不建议使用中文名称，会导致无法正常移动图片。

2.关于图片不同文件夹下名称相同，移动后会将同名的文件进行重命名，添加序号之类的，因此不会影响实际显示效果。

参考

sphinx官方文档