描述

使用 pip 安裝sphinx后，按照教程建立了一個(gè)新的py文件，如下

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

隨后新建一個(gè)目錄，使用 sphinx-quickstart 新建了sphinx環(huán)境，此時(shí)目錄結(jié)構(gòu)如下：

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

此時(shí)進(jìn)入 source目錄，在conf.py 中添加文件路徑，如下：

''' 遇到問題沒人解答？小編創(chuàng)建了一個(gè)Python學(xué)習(xí)交流QQ群：778463939 尋找有志同道合的小伙伴，互幫互助,群里還有不錯(cuò)的視頻學(xué)習(xí)教程和PDF電子書！ ''' import os import sys sys.path.insert(0, os.path.abspath('../..'))

然后在 doc 下執(zhí)行下面命令：

make htmlorsphinx-build -b html ./doc/source ./doc/build

發(fā)現(xiàn)兩個(gè)命令都可以正常生成文檔的模版，但并沒有生成注釋；即有生成的html，但沒有代碼的注釋/API文檔

嘗試解決

1

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

使用了一個(gè)docker鏡像，重試，結(jié)果是同樣的錯(cuò)誤
2

嘗試看非官方的教程，發(fā)現(xiàn)還需要更改 source 下的 index.rst；

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

''' 遇到問題沒人解答？小編創(chuàng)建了一個(gè)Python學(xué)習(xí)交流QQ群：778463939 尋找有志同道合的小伙伴，互幫互助,群里還有不錯(cuò)的視頻學(xué)習(xí)教程和PDF電子書！ ''' API === .. automodule:: run:members:

再次執(zhí)行，發(fā)現(xiàn)還有錯(cuò)，只不過提示不一樣了：提示

Unknown directive type “automodule” or “autoclass”

3

谷歌之，發(fā)現(xiàn)還要改一個(gè)配置的地方；位于 conf.py 里，增加一個(gè)擴(kuò)展……如下：

extensions = ['sphinx.ext.autodoc' ]

總結(jié)

以上是生活随笔為你收集整理的Python Sphinx使用踩坑记录的全部?jī)?nèi)容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網(wǎng)站內(nèi)容還不錯(cuò)，歡迎將生活随笔推薦給好友。