如何使用 Sphinx 记录 Python 包

2022-01-13 00:00:00 python python-sphinx package sphinx-apidoc

问题描述

我正在尝试用 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.

解决方案

这是一个大纲:

  1. 使用源中的文档字符串记录您的包.
  2. 使用 sphinx-quickstart 创建一个 Sphinx 项目.

  3. 运行 sphinx-apidoc 生成设置为与 autodoc 一起使用的 .rst 源.更多信息这里.

  1. Document your package using docstrings in the sources.
  2. Use sphinx-quickstart to create a Sphinx project.

  3. 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 or autoclass 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.

相关文章