Sphinx - 具有自动摘要功能的特定文件文档

发布于 2025-01-15 16:43:26 字数 1017 浏览 2 评论 0原文

我正在尝试使用 Sphinx 的自动摘要扩展来自动生成单个文件的方法的文档。我在 sphinx 上有以下文件夹结构

-docs
  -source
    -api.rst
    -conf.py
-src
  -players
    -a.py
    -b.py

我的 api.rst 如下

API
===

A
-
Description of file A
.. autosummary::
   :toctree: generated

   src.players.a

B
-
.. autosummary::
   :toctree: generated

   src.players.b

在文件 a.py 和 b.py 中，我有一个类，其中包含使用文档字符串记录的一些方法。

我想要的是在每个相应部分下查看该类及其方法的文档，但我无法使其工作。

在我的 conf.py 文件中，我添加了以下内容：

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

但它不会生成文档。我还尝试将 src/players 文件夹包含在路径中，但也没有成功。

一般来说，告诉 Sphinx 在哪里可以找到要记录的代码的首选方式是什么？

编辑：它抛出的错误如下

[autosummary] generating autosummary for: api.rst, index.rst, usage.rst
WARNING: [autosummary] failed to import src.players.a.
Possible hints:
* AttributeError: module 'src.players' has no attribute 'a'
* PycodeError: no source found for module 'src'

原文

I'm trying to use Sphinx's autosummary extension to generate the documentation automatically for the methods of a single file. I have the following folder structure on sphinx

-docs
  -source
    -api.rst
    -conf.py
-src
  -players
    -a.py
    -b.py

My api.rst is as follows

API
===

A
-
Description of file A
.. autosummary::
   :toctree: generated

   src.players.a

B
-
.. autosummary::
   :toctree: generated

   src.players.b

Where in file a.py and b.py I have a class with some methods documented using docstring.

What I would like is to see the class and its methods' documentation under each corresponding section, but I cannot make it work.

In my conf.py file I have added the following:

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

But it does not generate the documentation. I have also tried to include in the path the src/players folders, but no luck either.

In general, which is the preferred way to tell Sphinx where to find the code to be documented?

EDIT: The error it throws is the following

[autosummary] generating autosummary for: api.rst, index.rst, usage.rst
WARNING: [autosummary] failed to import src.players.a.
Possible hints:
* AttributeError: module 'src.players' has no attribute 'a'
* PycodeError: no source found for module 'src'

分享到QQ

分享到微博