使用sphinx生成API文檔

1、安裝sphinx?

pip install Sphinx

2、初始化文檔：

在項目根目錄下運行(或者進入doc目錄下執(zhí)行sphinx-quickstart)

sphinx-quickstart? doc?? #api文檔放在此目錄下

根據(jù)提示一步步來，我只處理下以下幾項，其它的都是默認回車

>? Separate source and build directories (y/n) [n]: y

>? Project name: TEST

>? Author name(s): X.F

>? Project language [en]: zh_cn

>? autodoc: automatically insert docstrings from modules (y/n) [n]: y

>? viewcode: include links to the source code of documented Python objects (y/n)? [n]: y

3、修改doc/source/conf.py

import? os

import? sys

import? django? #這個最好可以加載頂部和其他的 import 放在一起

sys.path.insert(0,? os.path.abspath('../..'))? #路徑指到項目根目錄

#

? 下面將 settings 加到環(huán)境變量里面，等一下啟動的時候就會是用這個配置

os.environ['DJANGO_SETTINGS_MODULE']? = 'JCSSJK.settings'

#

? 關(guān)鍵，用這句加載模塊和上下文

django.setup()

4、生成代碼文檔，到項目根目錄下：

注意:-o 后面跟的是保存rst文件的路徑，你的index.rst在哪個目錄，那你就指定哪個目錄。然后在后面的是你的項目(代碼)路徑

sphinx-apidoc? -o doc/source .

5、進入doc/source ，修改index.rst文件，讓其可以加載modules.rst內(nèi)容

..? toctree::?

:maxdepth:? 2?

:caption:? Contents:?

? modules? #加入此行

6、進入到doc目錄，運行 make html生成

??? 運行doc\build\html\index.html

7、為文檔更新一個友好的主題（先安裝pip install sphinx_rtd_theme）

再次修改doc/source/conf.py

#html_theme? = 'alabaster'?

import? sphinx_rtd_theme?

html_theme? = "sphinx_rtd_theme"?

html_theme_path? = [sphinx_rtd_theme.get_html_theme_path()]?

最后再重新運行一次 make html即可生效