sphinx
Sphinx 是一个工具，可以轻松创建由Georg Brandl编写并根据BSD许可证授权的智能和美观文档。
它最初是为Python文档创建的，它具有用于各种语言的软件项目文档的出色工具。当然，这个站点也是使用Sphinx从reStructuredText源创建的！
特性
应突出显示以下功能：
-
输出格式：HTML（包括Windows HTML帮助），LaTeX（适用于可打印的PDF版本），ePub，Texinfo，手册页，纯文本
-
广泛的交叉引用：语义标记和功能，类，引用，词汇表术语和类似信息的自动链接
-
分层结构：轻松定义文档树，自动链接到兄弟姐妹，父母和孩子
-
自动索引：一般索引以及特定于语言的模块索引
-
代码处理：使用Pygments荧光笔自动突出显示
-
扩展：自动测试代码片段，包含Python模块的文档字符串（API文档）等
-
贡献的扩展：用户在第二个存储库中贡献了50多个扩展;其中大多数可以从PyPI安装
标记语言
Sphinx 使用 reStructuredText 作为标记语言，它的许多优点来自reStructuredText及其解析和翻译套件Docutils的强大和直接性。
快速开始
本次测试环境为 macOS 系统。
mac pip 方式安装
- 更新 pip 版本
sudo pip install --upgrade pip
- 安装 sphinx
sudo pip install -U sphinx
快速开始
运行下面命令，依次指定配置。注意 autodoc 必须选择 yes，后面会说明如何使用。
相关命令语法参见：sphinx-apidoc
$ sphinx-quickstart
个人选择配置如下：
$ sphinx-quickstart
Welcome to the Sphinx 1.8.1 quickstart utility.
Please enter values for the following settings (just press Enter to
accept 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]: y
Inside the root directory, two more directories will be created; "_templates"
for custom HTML templates and "_static" for custom stylesheets and other static
files. You can enter another prefix (such as ".") to replace the underscore.
> Name prefix for templates and static dir [_]: _
The project name will occur in several places in the built documentation.
> Project name: test
> Author name(s): houbinbin
> Project release []: 0.0.1
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
http://sphinx-doc.org/config.html#confval-language.
> Project language [en]: en
The file name suffix for source files. Commonly, this is either ".txt"
or ".rst". Only files with this suffix are considered documents.
> Source file suffix [.rst]: .rst
One document is special in that it is considered the top node of the
"contents tree", that is, it is the root of the hierarchical structure
of the documents. Normally, this is "index", but if your "index"
document is a custom template, you can also set this to another filename.
> Name of your master document (without suffix) [index]: index
Indicate which of the following Sphinx extensions should be enabled:
> autodoc: automatically insert docstrings from modules (y/n) [n]: y
> doctest: automatically test code snippets in doctest blocks (y/n) [n]: y
> intersphinx: link between Sphinx documentation of different projects (y/n) [n]: y
> todo: write "todo" entries that can be shown or hidden on build (y/n) [n]: y
> coverage: checks for documentation coverage (y/n) [n]: y
> imgmath: include math, rendered as PNG or SVG images (y/n) [n]: y
> mathjax: include math, rendered in the browser by MathJax (y/n) [n]: y
> ifconfig: conditional inclusion of content based on config values (y/n) [n]: y
> viewcode: include links to the source code of documented Python objects (y/n) [n]: y
> githubpages: create .nojekyll file to publish the document on GitHub pages (y/n) [n]: n
Note: imgmath and mathjax cannot be enabled at the same time. imgmath has been deselected.
A Makefile and a Windows command file can be generated for you so that you
only have to run e.g. `make html' instead of invoking sphinx-build
directly.
> Create Makefile? (y/n) [y]: y
> Create Windows command file? (y/n) [y]: n
Creating file ./source/conf.py.
Creating file ./source/index.rst.
Creating file ./Makefile.
Finished: An initial directory structure has been created.
You should now populate your master file ./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 linkcheck.
运行命令之后，生成的文件如下：
Makefile build source
index.rst 欢迎界面简述
./source/index.rst. 里面使我们的欢迎页面。内容如下：
.. test documentation master file, created by
sphinx-quickstart on Sat Nov 10 10:43:30 2018.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
Welcome to test's documentation!
================================
.. toctree::
:maxdepth: 2
:caption: Contents:
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
build 构建
- 当前路径
$ pwd
/Users/houbinbin/_doc
$ ls
Makefile build source
- 运行构建
执行 make html
日志如下：
houbinbindeMacBook-Pro:_doc houbinbin$ make html
正在运行的是 Sphinx v1.8.1
创建输出目录…
loading intersphinx inventory from https://docs.python.org/objects.inv...
intersphinx inventory has moved: https://docs.python.org/objects.inv -> https://docs.python.org/3/objects.inv
构建 [mo]：0 个 po 文件的目标文件已过期
构建 [html]: 1 个源文件的目标文件已过期
updating environment: 1 added, 0 changed, 0 removed
reading sources... [100%] index
查找当前已过期的文件……没有找到
Pickle 序列化环境……完成
检查一致性……完成
准备文档……完成
写入输出……[100%] index
生成索引…… genindex
写入附加页面…… search
复制静态文件……done
复制额外文件……完成
导出 English (code: en) 的搜索索引……完成
导出对象清单……完成
构建 成功.
HTML 页面保存在 build/html 目录
查看
直接进入文件夹 build/html 查看即可：
页面效果如下：
参考资料
https://www.ibm.com/developerworks/cn/opensource/os-sphinx-documentation/index.html
- 安装
http://www.sphinx-doc.org/en/master/usage/installation.html
