用sphinx，git，readthedoc维护API文档

安装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

作者：拖鞋花短裤
链接：https://www.jianshu.com/p/9f8a83165944