20230418-用sphinx快速制作文档

Sphinx 快速制作文档

简介

sphinx 是一种文档工具，它可以令人轻松的撰写出清晰且优美的文档，由georg brandl 在bsd 许可证下开发，新版的python文档就是由sphinx 生成的，并且它已成为python项目的首选的文档工具，同时它对c++项目也有很好的支持，并计划对其他开发语言添加特殊支持，本站当然也是使用sphinx 生成的，它采用 reStructuredText Sphinx 还在继续开发，下面列出了其良好特性，这些特性在python官方文档中均有体现

丰富的输出格式，支持HTML 包括windows 帮助文档，latex 可以打印PDF版本，manual pages man 文档，纯文本

完备的交叉引用，语义化的标签，并可以自动化链接函数，类，引文，术语及相似的片段信息

明晰的分层结构 可以轻松的定义文档树，并自动化链接同级 父级 下级文章

美观的自动索引 可自动生成美观的模块索引

精确的语法高亮 基于pygments 自动生成语法高亮

开放的扩展，支持代码块的自动测试，并包含python模块的自述文档 api docs 等

sphinx 使用reStructureText 作为标记语言，可以享有docutils 为restructureText 提供的分析，转换等多种工具

安装sphinx

sphinx 为python 语言的一个第三方库，我们需要在终端中输入下列命令进行安装

pip install sphinx

创建 sphinx 项目

创建一个用于存放文档的文件夹，然后在该文件夹路径下运行下列命令快速生成sphinx 项目

sphinx-quickstart

接下来会让你选择一些配置

设置文档的根路径 回车 使用默认设置

是否分离source 和build 目录

设定模板前缀 回车 使用默认选项

输入项目名称和作者

输入项目版本号

文档语言 回车 默认即可

设定文档就按的后缀

设定首页名称 回车 选择默认index 即可

根据需要选择是否开启 epub 输出 一般用不到 回车默认不开启即可

根据需求选择是否开启相应的sphinx 拓展功能

创建项目以后目录结构如下所示

build 用来存放通过make html 生成文档网页文件的目录

source 存放用于生成文档的源文件

conf.py sphinx 的配置文件

index.rst 主文档

定义文档结构

主文档 index.rst 的主要功能是被转换成欢迎页，它包含一个目录表 table of contents tree 或者 toctree sphinx 主要功能是使用reStructureText 把许多文件组织成一份结构合理的文档

toctree 指令初始值如下

你可以在content 的位置添加文档列表

注 文档文件放在与index.rst 同级目录下

支持markdown 文件、更改文档主题

spinx 本身不支持md 文件生成文档，需要我们使用第三方库 recommonmark 进行转换，首先分别运行下列命令安装 recommonmark 与sphinx_rtd_theme 库

pip install recommonmark

pip install sphinx_rtd_theme

a安装好 在conf.py 中修改下列两个配置

并新增

source_parsers = {
    '.md': CommonMarkParser,
    '.MD': CommonMarkParser,
}

生成文档

在sphinx 项目所在的文件夹路径下运行下列命令生成文档

make html

生成后的文档位于 build/html 文件夹内，用浏览器打开index.html 即可看到生成后的文档

打赏