欢迎您访问程序员文章站本站旨在为大家提供分享程序员计算机编程知识!
您现在的位置是: 首页  >  IT编程

Python Sphinx使用踩坑记录

程序员文章站 2022-06-22 11:08:36
描述 使用 pip 安装sphinx后,按照教程建立了一个新的py文件,如下 run.py def run(name): """ this is how we run :param name name of people who runs """ print(name, 'is running') ......

描述

使用 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;

例如我们的代码文件是 ,需要把他加到 index.rst中,如下(run就是模块名称):

api
===
.. automodule:: run
   :members:

再次执行,发现还有错,只不过提示不一样了:提示

unknown directive type “automodule” or “autoclass”

3

谷歌之,发现还要改一个配置的地方;位于 里,增加一个扩展……如下:

extensions = [
        'sphinx.ext.autodoc'
]

此处参考了

再次尝试,终于成功了…

感想……

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