Python：文档工具Sphinx教程001

简介：Sphinx 是一种文档工具，它可以令人轻松的撰写出清晰且优美的文档, 由 Georg Brandl 在BSD 许可证下开发。新版的Python文档 就是由Sphinx生成的， 并且它已成为Python项目的文档工具,同时它对 C/C++ 项目也有很好的支持。

优势特性：

• 丰富的输出格式: 支持 HTML (包括 Windows 帮助文档), LaTeX (可以打印PDF版本), manual pages（man 文档）, 纯文本

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

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

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

• 的语法高亮: 基于 Pygments 自动生成语法高亮

• 开放的扩展: 支持代码块的自动测试,并包含Python模块的自述文档(API docs)等

安装：

pip install -U sphinx

创建sphinx项目：

sphinx-quickstart

创建后依次需要填的信息：

1、项目名称：任意

2、作者：任意

3、版本：任意

4、语言：zh_CN   中文

各个文件的作用：

build：生成的文件的输出目录

source: 存放文档源文件

_static：静态文件目录，比如图片等

_templates：模板目录

conf.py：进行 Sphinx 的配置，如主题配置等

index.rst：文档项目起始文件，用于配置文档的显示结构

cmd.bat：这是自己加的脚本文件（里面的内容是‘cmd.exe’）,用于快捷的打开windows的命令行

make.bat：Windows 命令行中编译用的脚本

Makefile：编译脚本，make 命令编译时使用

编译脚本：

make html

打开build\html文件：

安装autobuild工具：

pip install -i https://pypi.tuna.tsinghua.edu.cn/simple sphinx-autobuild

编译指令进行编译：

sphinx-autobuild source build/html

通过浏览器查看效果：http://127.0.0.1:8000/

自此，Sphinx文档工具快速搭建使用完成阶段一。

来源 https://www.modb.pro/db/241884