How to document Python packages using Sphinx(如何使用 Sphinx 记录 Python 包)
问题描述
我正在尝试用 Python 记录一个包.目前我有以下目录结构:
I am trying to document a package in Python. At the moment I have the following directory structure:
.
└── project
├── _build
│ ├── doctrees
│ └── html
│ ├── _sources
│ └── _static
├── conf.py
├── index.rst
├── __init__.py
├── make.bat
├── Makefile
├── mod1
│ ├── foo.py
│ └── __init__.py
├── mod2
│ ├── bar.py
│ └── __init__.py
├── _static
└── _templates
这棵树是 sphinx-quickstart
触发的结果.在 conf.py
我取消注释 sys.path.insert(0, os.path.abspath('.'))
并且我有 extensions = ['sphinx.ext.autodoc']
.
This tree is the result of the firing of sphinx-quickstart
. In conf.py
I uncommented sys.path.insert(0, os.path.abspath('.'))
and I have extensions = ['sphinx.ext.autodoc']
.
我的 index.rst
是:
.. FooBar documentation master file, created by
sphinx-quickstart on Thu Aug 28 14:22:57 2014.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
Welcome to FooBar's documentation!
==================================
Contents:
.. toctree::
:maxdepth: 2
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
在所有 __init__.py
中,我都有一个文档字符串,模块 foo.py
和 bar.py
也是如此.但是,在项目中运行 make html
时,我看不到任何文档.
In all the __init__.py
's I have a docstring and same goes to the modules foo.py
and bar.py
. However, when running make html
in the project I don't see any of the docstings.
推荐答案
这是一个大纲:
- 使用源中的文档字符串记录您的包.
- 使用 sphinx-quickstart 创建一个 Sphinx 项目.
运行 sphinx-apidoc 生成设置为与 autodoc 一起使用的 .rst 源.更多信息这里.
- Document your package using docstrings in the sources.
- Use sphinx-quickstart to create a Sphinx project.
Run sphinx-apidoc to generate .rst sources set up for use with autodoc. More information here.
将此命令与 -F
标志一起使用还可以创建一个完整的 Sphinx 项目.如果您的 API 变化很大,您可能需要多次重新运行此命令.
Using this command with the -F
flag also creates a complete Sphinx project. If your API changes a lot, you may need to re-run this command several times.
注意事项:
Sphinx 需要带有
automodule
或autoclass
等指令的 .rst 文件来生成 API 文档.如果没有这些文件,它不会自动从 Python 源中提取任何内容.这与 Epydoc 或 Doxygen 等工具的工作方式不同.此处对差异进行了详细说明:docutils 和 Sphinx 之间的关系是什么?.
Sphinx requires .rst files with directives like
automodule
orautoclass
in order to generate API documentation. It does not automatically extract anything from the Python sources without these files. This is different from how tools like Epydoc or Doxygen work. The differences are elaborated a bit more here: What is the relationship between docutils and Sphinx?.
运行 sphinx-apidoc 后,可能需要调整 conf.py 中的 sys.path
以便 autodoc 找到您的模块.
After you have run sphinx-apidoc, it may be necessary to adjust sys.path
in conf.py for autodoc to find your modules.
为了避免出现类似这些问题的奇怪错误,我应该如何解决OptionParser和sphinx-build的冲突大型项目?,OptionParser 是否与 sphinx 冲突?,确保代码结构正确,在需要时使用 if __name__ == "__main__":
守卫.
In order to avoid strange errors like in these questions, How should I solve the conflict of OptionParser and sphinx-build in a large project?, Is OptionParser in conflict with sphinx?, make sure that the code is properly structured, using if __name__ == "__main__":
guards when needed.
这篇关于如何使用 Sphinx 记录 Python 包的文章就介绍到这了,希望我们推荐的答案对大家有所帮助,也希望大家多多支持编程学习网!
本文标题为:如何使用 Sphinx 记录 Python 包


基础教程推荐
- 在 Python 中,如果我在一个“with"中返回.块,文件还会关闭吗? 2022-01-01
- 如何在海运重新绘制中自定义标题和y标签 2022-01-01
- Python kivy 入口点 inflateRest2 无法定位 libpng16-16.dll 2022-01-01
- 如何让 python 脚本监听来自另一个脚本的输入 2022-01-01
- 使用PyInstaller后在Windows中打开可执行文件时出错 2022-01-01
- 筛选NumPy数组 2022-01-01
- Dask.array.套用_沿_轴:由于额外的元素([1]),使用dask.array的每一行作为另一个函数的输入失败 2022-01-01
- 用于分类数据的跳跃记号标签 2022-01-01
- 线程时出现 msgbox 错误,GUI 块 2022-01-01
- 何时使用 os.name、sys.platform 或 platform.system? 2022-01-01