Sphinx 创建Python文档

使用文档生成工具 Sphinx 生成Python 代码文档

在Python 代码中使用docstring的注释方式，通过Sphinx可以自动生成文档。Sphix使用起来比较简单，不过在使用过程中还是踩雷了。

将正确的步骤整理如下：

• 安装Sphinx 

pip install sphinx

• 配置Sphinx环境
  • 在工作目录下创建docs 目录 
  • 进入docs目录
  • 执行sphix-quickstart

  • mkdir docs
    cd docs
    sphix-quickstart

    按照提示输入对应内容

                    

 

Sphinx将在docs目录下自动生成下图文件和目录

                     

 

• 　　配置docs/sourc/conf.py

修改python文件对应的目录，将愿conf.py中的注释的代码去掉注释

#
# import os
# import sys
# sys.path.insert(0, os.path.abspath('.'))

修改为python对应的目录，其中abspath('.')对应的目录是docs这个目录，我的python文件放在与docs平齐的目录下，所以修改为("../..")

import os
import sys
sys.path.insert(0, os.path.abspath('../..'))

　　　　加入napoleon extensions, 在代码中使用google style 或者 numpy style docstring（参考google style docstring ）
# Add napoleon to the extensions list
extensions = ['sphinx.ext.napoleon']

• 执行sphix-apidoc 生成rst文件（注意是在docs目录下执行）

• sphinx-apidoc -f -o source ../

  -f 意味强制更新已有的文件， source为生成的rst文件的目录， '../'为python代码目录

• 在index.rst文件中加入 "modules"行

• .. toctree::
     :maxdepth: 2
     :caption: Contents:
  
     modules

• 生成html文档

• make clean
  make html

   

按照上述步骤就能正常生成Python的html文档了。

其中踩了下面几个雷：

1.我的python代码文件中带有'-'，很不幸将文件命名为qt-painter.py，一直不能正常生成文档。将文件改名为qtpainter.py就能正常使用了。

2.修改相对目录的时候出错了，错误的修改为 ”./..",应该为“../.."

3.在修改index.rst文件的时候将modules拼写错了。