python文档生成

一、普通文档创建

pip install sphinx # 安装依赖
sphinx-quickstart # 创建文档向导

# 上一步将创建如下目录
├─build # 编译后的文件存放目录
└─source  # 文档源文件目录
    ├─_static
    ├─_templates
    ├─conf.py # 文档配置信息
    └─index.rst # 首页，rst为reStructuredText简写
└─make.bat
└─Makefile

先不用管太多，运行命令
sphinx-build -b html .\source .\build
或
make html
看一下生成的build下生成的文件，tree \f ./build

├─doctrees
│      environment.pickle
│      index.doctree
│
└─html # 生成的最终文档
    │  .buildinfo
    │  genindex.html
    │  index.html # 主文件
    │  objects.inv
    │  search.html
    │  searchindex.js
    │
    ├─_sources
    │      index.rst.txt
    │
    └─_static # 资源文件
            alabaster.css
            ...
            jquery.js
            ....
            minus.png
          

打开html/index.html 就可以看到文档。

解读一下index.rst, #之后的为注释，这不是rst文件的语法，只是为了说明内部含义

.. toctree::   # 文档入口方法
   :maxdepth: 2  # 参数为maxdepth, 值为2
   :caption: Contents: # 同上也是参数,综合以上，可以理解为调用了方法 toctree(maxdepth=2,caption='Contents')
                 # 空一行，以下代码不是自动生成，是为了说明语法而加入的。
    subdir1/subdir11 # 子目录1，其下须有 index.rst文件内含 ..toctree:: 命令,subdir11同样如此。 注意，这里由于maxdepth限定，所以只能到subdir11，第三级目录无法在该文件中添加
    subdir2 # 子目录2。可见index.rst文件就是组织文档结构的文件，子目录下保持这种结构，就可以完整的生成一个有层级的文档。

Indices and tables # 生成python文档时起作用
==================

* :ref:`genindex`  # * 表示li的记号，:ref:表示一个引用，genindex为 index:: 命令所产生的索引，见后面的代码，
* :ref:`modindex`
* :ref:`search`

.. index:: # 仅仅作为显示example，并没有对应到module，真实例子，须参考下面的说明
    single: 关键词1; 关键词2; 关键词3;   # 
    pair: 苹果; 香蕉
    triple: module; search; path

.. toctree::
rst格式参考
rst标记语言官方参

二、python 文档生成 参考

)
先创建两个python文件
mkdir src && cd src && touch demo1.py && touche demo2.py

• demo1.py

class Demo1():
    """类的功能说明"""

    def add(self,a,b):
        """两个数字相加，并返回结果"""
        return a+b
    
    def rest_style(self,a,b):
        """
        This is a reST style.

        :param a: 加数
        :param b: 被加数
        :returns: a+b
        :raises keyError: raises an exception
        """
        return a+b


    def google_style(self, arg1, arg2):
        """函数功能.

        函数功能说明.

        Args:
            arg1 (int): arg1的参数说明
            arg2 (str): arg2的参数说明

        Returns:
            bool: 返回值说明

        """
        return True

    def numpy_style(self, arg1, arg2):
        """函数功能.

        函数功能说明.

        Parameters
        ----------
        arg1 : int
            arg1的参数说明
        arg2 : str
            arg2的参数说明

        Returns
        -------
        bool
            返回值说明

        """
        return True

• demo2.py

def my_function(a, b):
    """函数功能说明 numpy style

     >>> my_function(2, 3)
     6
     >>> my_function('a', 3)
     'aaa'

    """
    return a * b

• 修改source/conf.py

# 文件首部，加入module 系统path，否则无法加载module
import os
import sys
sys.path.insert(0, os.path.abspath('../src'))

# 修改extension
extensions = ['sphinx.ext.autodoc',
    'sphinx.ext.doctest',
    'sphinx.ext.intersphinx',
    'sphinx.ext.todo',
    'sphinx.ext.coverage',
    'sphinx.ext.napoleon', # 兼容 google style和numpy style
    'sphinx.ext.mathjax']

• python文件转为rst文件
  sphinx-apidoc -o ./source ./src/
  可以看到source文件夹下多了三个文件:demo1.rst,demo2.rst,module.rst