【python】自动化生成项目文档

自动化生成项目文档

可以利用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-autogen

  • 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('.'))  
    

• 生成项目文档

  • sphinx-build
    usage: sphinx-build [OPTIONS] SOURCEDIR OUTPUTDIR [FILENAMES...]

    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

Sphinx国际化

扩展小技巧

• 导出Python项目安装模块
  pip freeze > requirements.txt

• 批量安装项目模块
  pip install -r requirements.txt