sphinx doc 文档生成脚手架工具

sphinx 在python 语言开发中，是一个使用的比较多文档生成脚手架工具，我们帮助我们生成
专业的帮助文档，同时也有远端的免费saas 托管服务，方便分发

安装

sphinx 的安装好多方便，mac 的可以使用brew，或者我们可以使用pip 安装,详细的可以参考官方文档

mac brew 安装方法

 

brew install sphinx-doc

pip 安装

pip install -U sphinx

简单demo

sphinx 提供了一个快速生成文档的命令，使用sphinx-quickstart 我们可以快速生成一个可用的文档项目

sphinx-quickstart

sphinx-quickstart
 

效果

欢迎使用 Sphinx 2.1.0 快速配置工具。

​

请输入接下来各项设置的值（如果方括号中指定了默认值，直接

按回车即可使用默认值）。

​

已选择根路径：.

​

布置用于保存 Sphinx 输出的构建目录，有两种选择。

一是在根路径下创建“_build”目录，二是在根路径下创建“source”

和“build”两个独立的目录。

> 独立的源文件和构建目录（y/n） [n]: y

​

项目名称会出现在文档的许多地方。

> 项目名称: dalongrongdemo

> 作者名称: dalong

> 项目发行版本 []: v1.0

​

如果用英语以外的语言编写文档，你可以在此按语言代码选择语种。

Sphinx 会把内置文本翻译成相应语言的版本。

​

支持的语言代码列表见：

http://sphinx-doc.org/config.html#confval-language。

> 项目语种 [en]: 

​

创建文件 ./source/conf.py。

创建文件 ./source/index.rst。

创建文件 ./Makefile。

创建文件 ./make.bat。

​

完成：已创建初始目录结构。

​

你现在可以填写主文档文件 ./source/index.rst 并创建其他文档源文件了。用 Makefile 构建文档，像这样：

 make builder

此处的“builder”是支持的构建器名，比如 html、latex 或 linkcheck。

生成html 页面

sphinx 使用make 进行项目管理，make 可以列出完整的命令

make html

正在运行 Sphinx v2.1.0

making output directory... 完成

构建 [mo]：0 个 po 文件的目标文件已过期

构建 [html]中: 1 个源文件的目标文件已过期

updating environment: 1 added, 0 changed, 0 removed

reading sources... [100%] index                                                                                                                        

查找当前已过期的文件……没有找到

pickling environment... 完成

checking consistency... 完成

preparing documents... 完成

写入输出……[100%] index                                                                                                                                     

生成索引…… genindex

写入附加页面…… search

复制静态文件……完成

复制额外文件……完成

导出 English (code: en) 的搜索索引……完成

导出对象清单……完成

构建 成功.

HTML 页面保存在 build/html 目录。

生成的内容

tree build 

build

├── doctrees

│ ├── environment.pickle

│ └── index.doctree

└── html

    ├── _sources

    │ └── index.rst.txt

    ├── _static

    │ ├── alabaster.css

    │ ├── basic.css

    │ ├── custom.css

    │ ├── doctools.js

    │ ├── documentation_options.js

    │ ├── file.png

    │ ├── jquery-3.2.1.js

    │ ├── jquery.js

    │ ├── language_data.js

    │ ├── minus.png

    │ ├── plus.png

    │ ├── pygments.css

    │ ├── searchtools.js

    │ ├── underscore-1.3.1.js

    │ └── underscore.js

    ├── genindex.html

    ├── index.html

    ├── objects.inv

    ├── search.html

    └── searchindex.js