Python Sphinx使用实例及问题解决

yipeiwu_com5年前Python基础

这篇文章主要介绍了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

再次尝试,终于成功了…

以上就是本文的全部内容,希望对大家的学习有所帮助,也希望大家多多支持【听图阁-专注于Python设计】。

相关文章

python 视频逐帧保存为图片的完整实例

我就废话不多说了,直接上代码吧! import cv2 import os def save_img(): video_path = r'F:\test\video1/' v...

使用50行Python代码从零开始实现一个AI平衡小游戏

使用50行Python代码从零开始实现一个AI平衡小游戏

  集智导读: 本文会为大家展示机器学习专家 Mike Shi 如何用 50 行 Python 代码创建一个 AI,使用增强学习技术,玩耍一个保持杆子平衡的小游戏。所用环境为...

浅谈编码,解码,乱码的问题

浅谈编码,解码,乱码的问题

在开发的过程中,我们不可避免的会遇到各种各样的编码,解码,或者乱码问题,很多时候,我们可以正常的解决问题,但是说实在的,我们有可能并不清楚问题到底是怎么被解决的,秉承知其然,更要知其所以...

Python使用import导入本地脚本及导入模块的技巧总结

本文实例讲述了Python使用import导入本地脚本及导入模块的技巧。分享给大家供大家参考,具体如下: 导入本地脚本 import 如果你要导入的 Python 脚本与当前脚本位于同一...

python实现网页自动签到功能

python实现网页自动签到功能

本文实例为大家分享了python实现网页自动签到功能的具体代码,供大家参考,具体内容如下 第1步、环境准备(用的chrome浏览器) 1.安装selenium包 pip instal...