Python Sphinx使用踩坑記錄

描述

使用 pip 安裝sphinx後，按照教程創建了一個新的py文件，以下

# run.py
def run(name):
    """
    this is how we run
    :param name name of people who runs
    """
    print(name, 'is running')

隨後新建一個目錄，使用 sphinx-quickstart 新建了sphinx環境，此時目錄結構以下：

- doc
    - Makefile
  - build/
  - make.bat
  - source/
- run.py

此時進入 source目錄，在conf.py 中添加文件路徑，以下：

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

而後在 doc 下執行下面命令：

make html

or

sphinx-build -b html ./doc/source ./doc/build

發現兩個命令均可以正常生成文檔的模版，但並無生成註釋；即有生成的html，但沒有代碼的註釋/API文檔

嘗試解決

1

開始以往是版本不一致，就從新建了virtualenv，仍是不行；

使用了一個docker鏡像，重試，結果是一樣的錯誤

2

嘗試看非官方的教程，發現還須要更改 source 下的 index.rst；

例如咱們的代碼文件是 run.py ，須要把他加到 index.rst中，以下（run就是模塊名稱）：

API
===
.. automodule:: run
   :members:

再次執行，發現還有錯，只不過提示不同了：提示

Unknown directive type 「automodule」 or 「autoclass」

3

谷歌之，發現還要改一個配置的地方；位於 conf.py 裏，增長一個擴展……以下：

extensions = [
        'sphinx.ext.autodoc'
]

此處參考了 https://stackoverflow.com/questions/13516404/sphinx-error-unknown-directive-type-automodule-or-autoclass

再次嘗試，終於成功了…

感想……

也許是我文檔看的不夠細，但實在是感受不太友好啊