使用sphinx自动生成python项目文档

在学校里读研的人都知道，老板时不时就会交代一些很烦的任务，而且很喜欢搞书面工作，比如搞一个什么项目，代码还没写多少，可能顶多就那么两三百行吧，就要求写文档，实在是坑。

好在鄙人平时写Python项目时就习惯使用Pycharm自动生成的注释（即，通过在某个类或者方法的声明下面敲 """ 在加一个回车生成），比如：

class Message:
    """
    Message class
    """
    def __init__(self, header: MessageType, data):
        """
        :param header:  Header of the message, specify the type of message
        :param data: Message data

        Initialize a Message
        """
        self.header = header
        self.data = data

于是我就想到这东西肯定可以自动产生文档。于是我随便搜索了一下，便找到了Sphinx这个库。

通过 pip install -U Sphinx 就安装了Sphinx。使用方法如下：

比如我的项目文件地址为./MyPythonProject，那就先建立一个文件夹./docs，之所以我不在项目文件夹里面建，是因为我不想混淆项目本身的文件和Sphinx的文件。

然后我把命令行cd到./docs文件夹里，然后运行命令sphinx-quickstart，这会让你填写一些简单的东西，如下：

Separate source and build directories (y/n) [n]: y
Project name: MyProject
Author name(s): JZM
Project release []: 0.0.1
Project language [en]:

这样之后在当前文件夹下生成两个文件夹：build 和 source，以及两个文件make.bat，makefile。其中source 文件夹包含了关于生成文档的一些配置参数，包括conf.py 和index.rst 两个重要文件。

在conf.py 中，要把前面的

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

注释去掉，同时把最后一行改成：sys.path.insert(0, os.path.abspath('../../MyPythonProject'))，因为这是我的Python项目相对于这个文件的位置。

同时需要加上extensions = ['sphinx.ext.autodoc',]。有了这个extension才能自动从Python文件中生成文档。

另一个文件是index.rst。这个文件指定要生成哪些文档。比如我有一个Python文件module.py在./MyPythonProject 目录下面，便可以在..toctree:: 那三行后面加上

.. automodule:: module
   :members:
   :undoc-members:

其中:members表示有注释的成员，:undoc-members表示未注释的成员（也可以加进文档里凑数，就是没有具体的说明，只有代码里的声明）。这个automodule会递归遍历module.py里面的类、成员、函数等。

注意到可能__init__ 方法中的注释会被忽略，因此需要在conf.py里面加上autoclass_content = 'both'。

同时，在Python代码中的注释也要按照rst的基本法来写，不能随心所欲，否则可能会报错。常用的也就是Pycharm自动生成的:param什么的，注意对于某个函数的注释，可以是

def function(a, b):
	"""
	Some description
	
	:param a: the first argument
	:param b: the seconde argument
	
	Some other description
	"""

:param 的列表前后都需要有空格。