<整理> 使用Python Sphinx自动生成代码文档

使用Sphinx自动生成代码文档

参考来源：
https://blog.csdn.net/sinat_29957455/article/details/83657029
https://www.cnblogs.com/xuzijie/p/9677621.html

欢迎讨论交流，如有侵权请联系本人！

• 版本信息

  Python 3.6.8 :: Anaconda, Inc.
  Sphinx 1.8.4

• 前置步骤

  1. 安装Python和pip，使用pip安装Sphinx。
  2. 在项目目录中创建src文件夹，用来存放源码；创建doc文件夹，用于存放Sphinx制作文档需要和将会产生的目录和文件。
  3. 项目Python源码需要有完整的docstring，docstring采用reStructuredText格式书写（简要书写方法请参考文末实例代码）。

• 生成步骤

  1. 在doc文件夹中执行sphinx-quickstart。

     关于sphinx-quickstart的配置页面有以下的说明：

     自动设置工作目录为当前文件夹
     Selected root path: .
     
     是否分离源文件和生成文件（默认为否，建议分离）
     > Separate source and build directories (y/n) [n]: y
     
     是否将模板文件夹和静态文件夹单独放到一个目录下（第一步设置分离后，默认在source文件夹下）
     > Name prefix for templates and static dir [_]: 
     
     项目名称，作者姓名和版本号（多作者的分隔符未知，请自行尝试）
     > Project name:
     > Author name(s):
     > Project release []:
     
     选择文档显示语言
     > Project language [en]:
     
     生成文档源文件的后缀（默认为“.rst"，也就是reStructuredText的缩写）
     >Source file suffix [.rst]: 
     
     生成文档的主页名称（默认为index)
     > Name of your master document (without suffix) [index]: 
     
     指定启用的扩展功能（此处仅说明我使用的两个，其他的用法请自行查阅）：
     将模块代码中的docstring插入到文档说明中
     > 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
     
     是否生成Makefile文件和Windows命令文件（生成后支持make html命令一键生成文档）
     > Create Makefile? (y/n) [y]:
     > Create Windows comand file? (y/n) [y]:
     

     等待程序执行完成后我们有以下目录结构：

     Project/
         src/
             code.py
         doc/
             build/
             Makefile
             source/
                 conf.py
                 index.rst
                 _static/
                 _templates/
     

  2. 由于我们是从源码中生成文档，需要修改Project/doc/source/conf.py文件：

     # import os
     # import sys
     # sys.path.insert(0, os.path.abspath('.'))
     
     # 修改为
     import os
     import sys
     # 将路径替换为你的源码路径
     sys.path.insert(0, os.path.abspath("../../src"))
     

     有需要的也可修改本文件的其他选项，在此不作详细说明。

  3. 使用sphinx-apidoc命令生成文档源文件：

     cd your_project_path
     # sphinx-apidoc -o [目标文件夹] [源文件夹]
     sphinx-apidoc -o ./doc/source ./src
     

     此时，在Project/doc/source/文件夹中会生成code.rst文件。

  4. 切换到Project/doc/目录下，使用make html命令就可以生成html格式的文档。生成的文档可在Project/doc/build/html/文件夹中查看。

reStructuredText格式的Python代码docstring示例（这里仅提供最简单的使用方式，具体语法请读者自行搜索学习）：

def your_func(your_param):
    """The description of your function, if there is a newline
    like this, do not indent to indicate that the description is
    not stop. Then you should leave a blank line to describe
    the parameters and return values.

    :param your_param: the description of your parameter,
      newline like this should indent two spaces.
    :type your_param: the type of your parameter.
    :return: the return values of your function. If your
      function return more than one values, you should use
      `:returns:` instead.
    :rtype: the type of return values.

    """
    # You should also add more description in other places to
    # make your documents more perfect. You can learn how
    # to write python docstring or just use "pylint" to help you
    # do this.