自动化生成项目文档
可以利用Sphinx根据代码块注释自动生成项目的文档
操作方法
-
Sphinx安装
pip install sphinx
-
生成Sphinx工作目录
mkdir doc cd doc
-
初始化文档项目
运行 sphinx-quickstart 获得下边目录结构
├─build └─source ├ ├─_static ├ └─_templates ├ ├─ conf.py ├ ├─ index.rst ├ make.bat ├ Makefile
-
生成Sphinx源文件
-
sphinx-apidoc
usage: sphinx-apidoc [OPTIONS] -o <OUTPUT_PATH> <MODULE_PATH> [EXCLUDE_PATTERN, ...]
根据代码块注释生成rst文档
-o <OUTPUT_PATH> 指定rst输出目录
<MODULE_PATH> 项目或文件目录
[EXCLUDE_PATTERN, …] 包含的文档构成的列表
-
添加工作环境
- conf.py中添加以下代码:
import os import sys sys.path.insert(0, os.path.abspath('.'))
- conf.py中添加以下代码:
-
生成项目文档
-
sphinx-build
usage: sphinx-build [OPTIONS] SOURCEDIR OUTPUTDIR [FILENAMES...]
扫描二维码关注公众号,回复: 6792250 查看本文章sphinx-build -b html source build
-b 指定输出格式
SOURCEDIR 指定conf.py所在目录
OUTPUTDIR 指定文档输出目录 -
make.bat
make html
sphinx-build 的封装.SOURCEDIR=source,OUTPUTDIR=build
-
文档
Sphinx官网:http://www.sphinx-doc.org/en/stable/index.html
config源码:http://www.sphinx-doc.org/en/stable/_modules/sphinx/config.html
reStructuredText简介:https://zh-sphinx-doc.readthedocs.io/en/latest/rest.html
Sphinx标记:https://zh-sphinx-doc.readthedocs.io/en/latest/markup/index.html
扩展小技巧
-
导出Python项目安装模块
pip freeze > requirements.txt
-
批量安装项目模块
pip install -r requirements.txt