如何通过Python Sphinx实例学习并解决相关问题？

本文共计646个文字，预计阅读时间需要3分钟。

这篇文章主要介绍了Python与Sphinx的使用实例及问题解决，通过示例代码展示了非详细的操作步骤，对有经验的学者或工作者具有一定的参考价值。需要的伙伴可以参考以下内容：

描述：使用pip安装Sphinx

使用：pip install sphinx

安装Sphinx后，可以通过以下步骤创建和生成文档：

1.创建一个新的Sphinx项目

2.编写文档

3.使用Sphinx命令生成HTML格式的文档

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

此处参考了 stackoverflow.com/questions/13516404/sphinx-error-unknown-directive-type-automodule-or-autoclass

再次尝试，终于成功了…

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