自動化生成項目文檔

自動化生成項目文檔

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