Python Sphinx使用实例及问题解决

更新时间：2020年01月17日 15:14:34 作者：wswang

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

再次尝试，终于成功了…

以上就是本文的全部内容，希望对大家的学习有所帮助，也希望大家多多支持脚本之家。

您可能感兴趣的文章:

简单了解Python3里的一些新特性
这篇文章主要介绍了简单了解Python3里的一些新特性，给大家总结一下Python3一些新的更方便的特性！希望你们看完后也能高效率的编写代码,需要的朋友可以参考下
2019-07-07
Pandas数据集的合并与连接merge()方法
Pandas数据集的合并与连接（merge()）是数据处理过程中常用的操作之一,在使用Pandas进行数据集合并时,可以使用merge()函数将两个或多个数据集按照指定的列进行合并,本文就来介绍一下,感兴趣的可以了解一下
2023-11-11
Python+Redis实现布隆过滤器
布隆过滤器（Bloom Filter）是1970年由布隆提出的。它实际上是一个很长的二进制向量和一系列随机映射函数。这篇文章主要介绍了Python+Redis实现布隆过滤器,需要的朋友可以参考下
2019-12-12
keras 获取某层输出获取复用层的多次输出实例
这篇文章主要介绍了keras 获取某层输出获取复用层的多次输出实例，具有很好的参考价值，希望对大家有所帮助。一起跟随小编过来看看吧
2020-05-05
全CPU并行处理Pandas操作Pandarallel更快处理数据
我们在处理数据时,通常小的数据对处理速度不敏感,但数据量一大,顿时会感觉数据处理效率不尽如人意,今天介绍的pandarallel就是一个简单高效的Pandas并行工具,几行代码就可以提高数据处理效率,
2024-01-01
python文件名和文件路径操作实例
下面小编就为大家带来一篇python文件名和文件路径操作实例。小编觉得挺不错的，现在就分享给大家，也给大家做个参考。一起跟随小编过来看看吧
2017-09-09
详解Python中的Dict
这篇文章主要为大家介绍了Python中的Dict，具有一定的参考价值，感兴趣的小伙伴们可以参考一下，希望能够给你带来帮助
2021-12-12
Python数据库小程序源代码
这篇文章主要介绍了Python数据库小程序源代码，非常不错，具有一定的参考借鉴价值,需要的朋友可以参考下
2019-09-09
MacBook m1芯片采用miniforge安装python3.9的方法示例
这篇文章主要介绍了MacBook m1芯片采用miniforge安装python3.9的方法示例，文中通过示例代码介绍的非常详细，对大家的学习或者工作具有一定的参考学习价值，需要的朋友们下面随着小编来一起学习学习吧
2021-04-04
python数组和矩阵的用法解读
这篇文章主要介绍了python数组和矩阵的用法，具有很好的参考价值，希望对大家有所帮助。如有错误或未考虑完全的地方，望不吝赐教
2023-05-05