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

再次尝试，终于成功了…

感想……

也许是我文档看的不够细，但实在是感受不太友好啊