使用sphinx生成API文档

使用sphinx生成API文档

1、安装sphinx 

pip install Sphinx

2、初始化文档：

在项目根目录下运行(或者进入doc目录下执行sphinx-quickstart)

sphinx-quickstart  doc   #api文档放在此目录下

根据提示一步步来，我只处理下以下几项，其它的都是默认回车

>  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 加到环境变量里面，等一下启动的时候就会是用这个配置

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

#

  关键，用这句加载模块和上下文

django.setup()

4、生成代码文档，到项目根目录下：

注意:-o 后面跟的是保存rst文件的路径，你的index.rst在哪个目录，那你就指定哪个目录。然后在后面的是你的项目(代码)路径

sphinx-apidoc  -o doc/source .

5、进入doc/source ，修改index.rst文件，让其可以加载modules.rst内容

..  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即可生效