代码文档

文档主要用sphinx来生成。

新建一个文档

sphinx-quickstart

会有几个问题，如工程名称以及作者等，输入即可。

修改文档主题

修改为read the doc的主题，在conf.py中做如下修改。

将 extensions = [] 删掉，并换为：

extensions = ['sphinx.ext.todo', 'sphinx.ext.viewcode' 'sphinx.ext.autodoc']

将 html_theme = 'alabaster' 修改为 html_theme = "sphinx_rtd_theme",
并添加如下代码：

import sphinx_rtd_theme
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]

在sphinx中使用markdown标记

添加如下内容到conf.py中：:

source_parsers = {
'.md': 'recommonmark.parser.CommonMarkParser',
}

添加Markdown的文件扩展名到配置文件的source_suffix变量：:

source_suffix = ['.rst', '.md']

https://sphinx-apidoc.readthedocs.io/zh_CN/latest/more/markdown.html

生成文档

在doc目录下执行make html, 就会在doc/build/html下生成网页格式的文档了。

只有代码注释，没有自定义页面、文档时的首页

主页的位置在doc/source/index.rst, 如下图所示。

主页的源文件很简单，可以简单修改如下所示：

.. facemodel documentation master file, created by
   sphinx-quickstart on Wed Sep 18 20:28:48 2019.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

脸模API文档
=====================================

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   test
   test2

索引与表格
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

我们只是简单修改增加了test和test2，这表明sphinx会在source目录中寻找test.rst和test2.rst作为本页面的子页面。

其中深度为2表示文档必须有一个标题. 这些文档内的指令toctree也会被插入.

产生多级页面

紧接着上面的实验，我们新建doc/source/ch02文件夹，并在该文件夹下新建01.rst和02.rst两个文件。现在这两个文件是孤立的，在test.rst或者test2.rst中也插入一个tcotree指令，完成对文件的包含。

.. toctree::
   :maxdepth: 3
   
   ch02/01
   ch02/02

完成多级页面后的效果如下：

但有个问题，在浏览包含有toctree指令的页面时，总是将子页面的标题也展示出来。

文档标记

reStructuredText 是扩展名为.rst的纯文本文件，含义为”重新构建的文本”，也被简称为：RST或reST；是Python编程语言的Docutils项目的一部分，
Python Doc-SIG (Documentation Special Interest Group)。该项目类似于Java的JavaDoc或Perl的POD项目。
Docutils 能够从Python程序中提取注释和信息，格式化成程序文档。

.rst 文件是轻量级标记语言的一种，被设计为容易阅读和编写的纯文本，并且可以借助Docutils这样的程序进行文档处理，

也可以转换为HTML或PDF等多种格式，或由Sphinx-Doc这样的程序转换为LaTex、man等更多格式

具体的文档标记见下节。

生成sitemap

安装插件

pip install sphinx-sitemap

将sphinx-sitemap放进扩展的数组中。

extensions = ['sphinx_sitemap']

同时设置url基础路径

html_baseurl = 'https://my-site.com/docs/'

在使用中说明，如果conf.py中存在language = 'zh-cn'语句，在生成的sitemap的url为变为baseurl/zh-cn//dir/file, 不仅多了语言的url，还多了一个/, 去掉语言设置就好了。

pypi说明 https://pypi.org/project/sphinx-sitemap/

使用sphinx碰到的错误

/home/wenfeng/workspace/facemodel/doc/source/api.rst:4: WARNING: Unknown directive type "automodule".

.. automodule:: api
   :members:
   :undoc-members:
   :show-inheritance:

解决方案：
在doc/source/conf.py中检查extensions项，并增加为如下内容

extensions = [‘sphinx.ext.todo’, ‘sphinx.ext.viewcode’, ‘sphinx.ext.autodoc’]

错误

reading sources... [100%] servo                                                                                    
WARNING: autodoc: failed to import module 'api'; the following exception was raised:
No module named 'api'

解决方案:
在doc/source/conf.py中增加如下代码，确保sphinx可以看到我们的代码

import os
import sys
sys.path.insert(0, os.path.abspath('./../../src'))

参考

todo

sphinx 安装、配置、主题、使用
sphinx 注释的格式
sphinx 写自己的章节等
sphinx 主页修饰

测试
代码规范扫描

自动生成文档 Sphinx

rtd 主题配置
https://sphinx-rtd-theme.readthedocs.io/en/latest/configuring.html

其他sphinx 的众多有用的配置
http://www.sphinx-doc.org/en/master/usage/configuration.html