使用 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 生成
评论1