Python Sphinx使用实例及问题解决

所属分类: 脚本专栏 / python 阅读数: 2000
收藏 0 赞 0 分享

这篇文章主要介绍了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实现图像几何变换的方法,实例分析了Python基于Image模块实现图像翻转、旋转、改变大小等操作的相关技巧,非常简单实用,需要的朋友可以参考下
收藏 0 赞 0 分享

Python中的urllib模块使用详解

这篇文章主要介绍了Python中的urllib模块使用详解,是Python入门学习中的基础知识,需要的朋友可以参考下
收藏 0 赞 0 分享

Python的多态性实例分析

这篇文章主要介绍了Python的多态性,以实例形式深入浅出的分析了Python在面向对象编程中多态性的原理与实现方法,需要的朋友可以参考下
收藏 0 赞 0 分享

python生成IP段的方法

这篇文章主要介绍了python生成IP段的方法,涉及Python文件读写及随机数操作的相关技巧,具有一定参考借鉴价值,需要的朋友可以参考下
收藏 0 赞 0 分享

python操作redis的方法

这篇文章主要介绍了python操作redis的方法,包括Python针对redis的连接、设置、获取、删除等常用技巧,具有一定参考借鉴价值,需要的朋友可以参考下
收藏 0 赞 0 分享

python妹子图简单爬虫实例

这篇文章主要介绍了python妹子图简单爬虫,实例分析了Python爬虫程序所涉及的页面源码获取、进度显示、正则匹配等技巧,需要的朋友可以参考下
收藏 0 赞 0 分享

分析用Python脚本关闭文件操作的机制

这篇文章主要介绍了分析用Python脚本关闭文件操作的机制,作者分Python2.x版本和3.x版本两种情况进行了阐述,需要的朋友可以参考下
收藏 0 赞 0 分享

python实现搜索指定目录下文件及文件内搜索指定关键词的方法

这篇文章主要介绍了python实现搜索指定目录下文件及文件内搜索指定关键词的方法,可实现针对文件夹及文件内关键词的搜索功能,需要的朋友可以参考下
收藏 0 赞 0 分享

python中getaddrinfo()基本用法实例分析

这篇文章主要介绍了python中getaddrinfo()基本用法,实例分析了Python中使用getaddrinfo方法进行IP地址解析的基本技巧,需要的朋友可以参考下
收藏 0 赞 0 分享

python查找指定具有相同内容文件的方法

这篇文章主要介绍了python查找指定具有相同内容文件的方法,涉及Python针对文件操作的相关技巧,需要的朋友可以参考下
收藏 0 赞 0 分享
查看更多