如何使用Sphinx记录Python软件包

Question

如何使用Sphinx记录Python软件包

13

我正在尝试记录一个Python包。目前，我的目录结构如下：

.
└── 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']。

我的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命令后，我看不到任何文档字符串。

- Dror

你只有一个顶级的index.rst文件，但这还不够。你需要运行sphinx-apidoc来生成所需的.rst源文件（或者手动创建它们）。 - mzjn

Sphinx需要包含指令（如automodule或autoclass）的.rst文件才能生成API文档。如果没有这些指令，它就无法从源代码中提取信息。也许您期望Sphinx像Epydoc或Doxygen一样工作，但实际上并非如此。请参阅以下答案：https://dev59.com/y3E95IYBdhLWcg3wI6bt#2441159，https://dev59.com/YG025IYBdhLWcg3wRTxK#6109098。 - mzjn

1

让我们在聊天中继续这个讨论。点击此处进入聊天室。 - Dror

1

刚刚用PyCharm写了一个完整的工作示例，可以用作灵感。https://dev59.com/C6Xja4cB1Zd3GeqPP1u0#46362065 - Ferhat

1个回答

网页内容由stack overflow 提供, 点击上面的

可以查看英文原文，
原文链接

- mzjn · Accepted Answer

这是一个大纲：

使用源代码中的文档字符串记录您的软件包。
使用sphinx-quickstart创建Sphinx项目。
运行sphinx-apidoc生成.rst源文件，以便与autodoc一起使用。更多信息请查看此处。

使用该命令并带有-F标志还会创建完整的Sphinx项目。如果您的API经常发生变化，则可能需要多次运行此命令。
使用sphinx-build构建文档。

注意事项：

Sphinx需要.rst文件，并使用像automodule或autoclass这样的指令来生成API文档。如果没有这些文件，它不会自动从Python源代码中提取任何内容。这与Epydoc或Doxygen等工具的工作方式不同。这些差异在这里有更详细的阐述：docutils和Sphinx之间的关系是什么？。
在运行sphinx-apidoc之后，可能需要在conf.py中调整sys.path，以便autodoc找到您的模块。
为了避免像这些问题中出现的奇怪错误，我应该如何解决大型项目中OptionParser和sphinx-build的冲突？, OptionParser是否与sphinx冲突？，请确保代码结构正确，并在需要时使用if __name__ == "__main__":保护。