使用 Sphinx 的 Python 文档：不会生成文档字符串文档

Question

我正在尝试使用 Sphinx 6.2.1 和 Python3 生成我的项目文档。我正在处理一个名为

sphinx-basic-test

的测试项目。我创建了一个

docs

文件夹并在其中运行

sphinx-quickstart

。到目前为止，我的项目结构是：

sphinx-basic-test
-code
    |__ __init__.py
    |__ classifiers.py (several functions)
    |__ clean_data.py  (a class, with main method)
    |__ data_tools.py  (several functions)
- docs
    |__ Makefile
    |__ _build
    |__ _static
    |__ _templates
    |__ conf.py
    |__ index.rst
    |__ make.bat

我遵循了几个教程、stackoverflows 线程和官方文档：

• 我修改了

  conf.py

  文件，添加了以下几行：

import sys
sys.path.insert(0, os.path.abspath('..'))

extensions = ['sphinx.ext.autodoc', 'sphinx.ext.coverage', 'sphinx.ext.napoleon']

• 然后我在根文件夹 (

  sphinx-apidoc -o docs code/

  ) 中运行以下行：

  sphinx-basic-test

  。它创建了文件

  docs/code.rst

  和

  docs/modules.rst

  。第一篇的内容是：

code package
============

Submodules
----------

code.classifiers module
-----------------------

.. automodule:: code.classifiers
   :members:
   :undoc-members:
   :show-inheritance:

code.clean\_data module
-----------------------

.. automodule:: code.clean_data
   :members:
   :undoc-members:
   :show-inheritance:

code.data\_tools module
-----------------------

.. automodule:: code.data_tools
   :members:
   :undoc-members:
   :show-inheritance:

而第二个的内容很简单：

code
====

.. toctree::
   :maxdepth: 4

   code

• 我修改了

  index.rst

  文件以添加

  modules

  处理标识：

Welcome to test's documentation!
================================

.. toctree::
   :maxdepth: 2
   :caption: Contents:
   
   modules

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

• 完成此操作后，我在

  make html

  文件夹中运行

  docs

  。这会引发很多警告，所有类型：

  WARNING: autodoc: failed to import module 'classifiers' from module 'code'; the following exception was raised: No module named 'code.classifiers'; 'code' is not a package 

• 我检查了创建的html文件，它确实显示了不同函数和类的名称（但不是类内的方法），但没有生成文档。到目前为止，我已经尝试了几件事，包括更改配置文件中的abs.path，但没有不同的输出。

• 我得到的唯一不同的结果是不使用

  sphinx-apidoc

  ，而只是编写如下块：

.. automodule:: classifiers
   :members:

在

index.rst

文件中。但这仅适用于其中一个脚本，如果我尝试也以这种方式添加

clean_data

，它将不起作用。

我想创建 html 文件，以便使用 python 文件中的文档字符串记录所有三个脚本，以及我想添加的其他信息。但我陷入了第一个目标，非常感谢任何帮助。

Answer 1

看来你已经快到了！您遇到的问题可能是由于您在文档中引用模块名称的方式以及您构建项目的方式造成的。让我们详细了解一下使您的项目文档与 Sphinx 正常工作的步骤和潜在的解决方案。

首先，确保你的项目结构清晰：

sphinx-basic-test
├── code
│   ├── __init__.py
│   ├── classifiers.py
│   ├── clean_data.py
│   └── data_tools.py
└── docs
    ├── Makefile
    ├── _build
    ├── _static
    ├── _templates
    ├── conf.py
    ├── index.rst
    └── make.bat

Conf.py 更改：您已经将项目路径插入到 sys.path 中，这是正确的：

import os
import sys
sys.path.insert(0, os.path.abspath('..'))

extensions = ['sphinx.ext.autodoc', 'sphinx.ext.coverage', 'sphinx.ext.napoleon']

使用 sphinx-apidoc：运行 sphinx-apidoc 时，将为模块生成 .rst 文件。但是，您在 index.rst 中引用它们的方式可能会导致问题。 在您的index.rst中，更改对模块的引用以使用点表示法：

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   code.classifiers
   code.clean_data
   code.data_tools

模块的 Autodoc：在 sphinx-apidoc 生成的 .rst 文件中，您不需要在模块引用中包含“代码”部分，因为您已经将父目录插入到路径中。例如，在 docs/code.rst 中：

classifiers module
-------------------

.. automodule:: classifiers
   :members:
   :undoc-members:
   :show-inheritance:

类和函数的 Autodoc：确保您的类和函数具有正确的文档字符串。 Sphinx 将自动提取并显示这些文档字符串。对于类，方法也应该有文档字符串。 完成这些更改后，尝试在 docs 目录中再次运行 make html。这应该生成包含正确导入的模块、类、函数及其相关文档字符串的文档。

请记住，.rst 文件中的结构和引用应与项目在模块名称和层次结构方面的组织方式保持一致。如果您对代码结构或模块命名进行任何更改，请务必相应地调整文档中的引用。

考虑学习这个 python 教程来增强您的学习。