問題描述

我正在嘗試用 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.

這篇關于如何使用 Sphinx 記錄 Python 包的文章就介紹到這了，希望我們推薦的答案對大家有所幫助，也希望大家多多支持html5模板網！