安装sphinx：
# apt install python-pip
# pip install sphinx
# pip install sphinx_rtd_theme
# mkdir -p doc
# cd doc
# sphinx-quickstart
Note that some configurations needto change:
> Separate source and build directories (y/N) [n]:
y
> Name prefix for templates and static dir [_]:
> Project name:
ABC
> Author name(s):
Aarpm
> Project version:
1.0
> 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
> ifconfig: conditional inclusion of content based on config values (y/N) [n]:
y
> Create Makefile? (Y/n) [y]:
y
> Create Windows command file? (Y/n) [y]:
y
配置sphinx：
# vim source/conf.py
Uncomment:
"
import os
import sys
sys.path.insert(0,os.path.abspath('..'))
"
Add lines as follows:
autodoc_mock_imports = ['xx'] /*这部分的内容取决于项目需要stub的python模块，主要用作做mock那些无法正常import的模块*/
extensions = [
'sphinx.ext.autodoc',
'sphinx.ext.intersphinx',
'sphinx.ext.ifconfig',
'sphinx.ext.doctest',
'sphinx.ext.todo',
'sphinx.ext.coverage',
'sphinx.ext.viewcode', /*该选项可以让你在web上直接点击API来浏览源代码*/
]
html_theme = 'sphinx_rtd_theme'
# sphinx-apidoc -f -o ./source/home/xx/<your project folder>
# make html
Running Sphinx v1.7.5
loading pickled environment... done
building [mo]: targets for 0 pofiles that are out of date
building [html]: targets for 0source files that are out of date
updating environment: 0 added, 1changed, 0 removed
reading sources... [100%]api.generic
looking for now-outdated files...none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] index
generating indices... genindexpy-modindex
highlighting module code... [100%]api.structures.objects
writing additional pages... search
copying static files... done
copying extra files... done
dumping search index in English(code: en) ... done
dumping object inventory... done
build succeeded.
The HTML pages are in build/html.
修改生成的*.rst做格式调整（斜体部分为范例）
For index.rst
Welcome to xx documentation!
===============================
.. toctree::
:maxdepth: 2
:caption: Contents:
api.adapter
api.generic
api.structures
Remove 'package', 'submodule' stuff in other rst file
api.adapter
===================
.. toctree::
:maxdepth: 2
:numbered: 2 ---- mark for number displaying
api.adapter.xx
api.adapter.xx
git push你的改动
# git add .
# git commit -m "xx"
# git push origin master
git中添加web hook
托管网站会自动编译并识别其中的rst文件，访问https://<your project name>.readthedocs.io/en/latest/index.html来查看最终的效果。
