如何使用Sphinx记录Python软件包 [英] How to document Python packages using Sphinx

问题描述

我正在尝试用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以便自动文档找到您的模块.

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软件包的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！