安装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?？椋饕米髯鰉ock那些无法正常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来查看最终的效果。
