這篇文章主要介紹了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文件

嘗試解決

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

使用了一個docker映象，重試，結果是同樣的錯誤

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

例如我們的程式碼檔案是 run.py ，需要把他加到 index.rst中，如下（run就是模組名稱）：

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

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

Unknown directive type “automodule” or “autoclass”

谷歌之，發現還要改一個配置的地方；位於 conf.py 裡，增加一個擴充套件……如下：

extensions = [
    'sphinx.ext.autodoc'
]

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

再次嘗試，終於成功了…

以上就是本文的全部內容，希望對大家的學習有所幫助，也希望大家多多支援我們。