如何從 Python 中的文檔字符串創建文檔？

Python 中有一種特殊的字符串稱為“文檔字符串”，通常用來記錄函數、方法、類等的相關信息。愛掏網 - it200.com這些文檔字符串可以通過一定的方式自動生成易于閱讀的文檔，為用戶提供方便。愛掏網 - it200.com

那么，如何從 Python 中的文檔字符串創建文檔呢？本文將介紹兩種常用的方式。愛掏網 - it200.com

Pydoc 是 Python 編程語言自帶的一種文檔生成工具。愛掏網 - it200.com它可以從 Python 的模塊、包、類、函數等文檔字符串中自動生成 HTML 格式的文檔。愛掏網 - it200.com使用 Pydoc 生成文檔十分簡單，只需運行以下命令：

python -m pydoc -w module_name

其中，module_name 是需要生成文檔的 Python 模塊的名稱，如下所示：

def say_hello(name):
    """
    This function prints a greeting message with the given name.

    Parameters:
    name (str): The name to be greeted.

    Returns:
    None
    """
    print("Hello, " + name + "!")

我們可以將上述代碼保存為 example.py 文件，然后在命令行中運行如下命令：

python -m pydoc -w example

此時，將會在當前目錄下生成一個名為 example.html 的文件，打開該文件即可查看生成的文檔。愛掏網 - it200.com

此外，還可以使用 -p 參數指定端口號，從而在瀏覽器中查看生成的文檔：

python -m pydoc -p 8000 -b

以上命令將會在本地啟動一個 Web 服務器，然后在瀏覽器中訪問 http://localhost:8000 就能看到文檔了。愛掏網 - it200.com

使用 Sphinx 自動生成文檔

Sphinx 是一款流行的文檔生成工具，它支持從多種格式的文檔中生成 HTML、PDF、EPUB 等多種輸出格式的文檔。愛掏網 - it200.com其中，Sphinx 最常用的文檔格式是 reStructuredText（簡稱 RST），與 Markdown 類似，但功能更強大。愛掏網 - it200.com

要使用 Sphinx 自動生成文檔，首先需要安裝 Sphinx。愛掏網 - it200.com可以使用如下命令安裝：

pip install -U Sphinx

安裝完成后，在 Python 模塊的目錄下執行以下命令：

sphinx-quickstart

Sphinx 會在當前目錄下創建一個名為 docs 的目錄，并生成一些配置文件。愛掏網 - it200.com接著，在 docs 目錄下創建一個名為 index.rst 的文件，該文件就是生成的文檔的入口文件。愛掏網 - it200.com

然后，我們需要在 index.rst 文件中添加需要生成文檔的 Python 模塊的文檔字符串，如下所示：

example module
==============

.. automodule:: example
    :members:

其中，.. automodule:: example 表示自動導入 example 模塊的所有內容，:members: 表示生成成員列表。愛掏網 - it200.com這樣，就可以生成 example 模塊的 API 文檔了。愛掏網 - it200.com

接著，在命令行中切換到 docs 目錄下，運行以下命令來生成文檔：