使用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 的列表前後都需要有空格。