如何使用Sphinx記錄簡單的Python腳本？

Question

我已經閱讀了許多Sphinx教程，但仍然想不出如何使Sphinx文檔成為一個像這樣的簡單Python腳本：

def addNumbers(a):
    """This function adds one to the given number.

    :param a: The name to use
    :type a: int

    """
    b = a + 1
    print b

addNumbers(5)

以下是我要做的步驟。 我想念什么？

安裝Sphinx：

pip install sphinx

在我的項目目錄中創建一個文檔目錄：

mkdir docs

從新的doc目錄內部運行sphinx-quickstart ，然后按Enter回答除以下兩個問題以外的所有問題：

Separate source and build directories (y/n) [n]: y
autodoc: automatically insert docstrings from modules (y/n) [n]: y

這使我的項目目錄結構變為：

myproject/ 
|-- docs/
    |-- build/
    |-- source/
    make.bat
    Makefile
|-- mycode/ 
    myscript.py 

打開conf.py ，取消注釋以下幾行，並添加我的代碼所在的文件夾的路徑：

import os
import sys
sys.path.insert(0, os.path.abspath('C:\myproject\mycode'))

從我的docs目錄運行以下命令：

make html

這給了我以下確認，沒有錯誤：

現在，當我打開C：\\ myproject \\ docs \\ build \\ html \\ index.html時，僅看到以下內容，而沒有原始文檔中插入的文檔字符串的信息。 單擊“模塊索引”會顯示“找不到文件”錯誤。 這是為什么？

編輯：完成上述所有步驟之后，我添加了一個文件夾mypackage並在其中復制了包含我的代碼的文件，使目錄內容如下所示：

myproject/ 
|-- docs/
    |-- build/
    |-- source/
    make.bat
    Makefile
|-- mycode/ 
    myscript.py 
|-- mypackage/ 
    myscript.py 

然后，我從doc目錄運行以下命令：

sphinx-apidoc -f -o source/ ../mypackage/
make html

現在，單擊“模塊索引”可以看到以下內容：

然后單擊myscript得到：

現在的問題是，為什么我的主腳本myscript.py列在模塊下而不是文檔首頁上？

Answer 1

為了使Python將目錄視為包含包，需要__init__.py文件。 請參閱軟件包的Python教程文檔 。

我的猜測是sphinx-apidoc將您的腳本識別為腳本，而不是程序包，因為您省略了__init__.py文件。 根據sphinx-apidoc的文檔：

sourcedir必須指向Python包。

在文檔下方也有一個警告：

如果您編寫腳本（而不是庫模塊），請確保腳本的主例程受到if __name__ == '__main__'條件的保護。

在看不到您的代碼的情況下，我將從__init__.py文件開始，看看是否可以解決它。