Question

作为最小示例，我具有以下程序包结构（为方便起见，所有文件都上传了here）：

.
├── sphinx
│   ├── build
│   ├── Makefile
│   └── source
│       ├── conf.py
│       ├── index.rst
│       └── train.rst
└── train
    ├── __init__.py
    └── train.py

在编写Python软件包时，必须在任何软件包的__all__中指定__init__.py常量，以便Sphinx能够将诸如train.DatasetMeta之类的引用映射到{{1 }}或类似。但是，train.train.DatasetMeta为这些软件包生成以下部分：

sphinx-apidoc

由于包含train package ============= Submodules ---------- train.train module ------------------ .. automodule:: train.train :members: :undoc-members: :show-inheritance: Module contents --------------- .. automodule:: train :members: :undoc-members: :show-inheritance:和.. automodule:: module.file，它们都引用相同的内容，因此会重复整个文档。删除这两个部分中的任何一个都会导致未定义的参考警告（在使用.. automodule:: module至-n时变成错误）。

SPHINXOPTS

我该如何解决？

train / train.py

sphinx_test/train/train.py:docstring of train.DatasetMeta:1:py:class reference target not found: train.train.DatasetMeta

train / __ init __。py

from collections import namedtuple


class DatasetMeta(namedtuple('DatasetMeta', ['dataset', 'num_classes', 'shape'])):
    @property
    def size(self):
        '''int: Number of examples in the dataset'''
        return self.shape[0]

sphinx / source / conf.py

from .train import *

__all__ = ['DatasetMeta']

我只是无法弄清楚这里的逻辑。

Answer 1

我们可以做的一件事情来简化这种情况：

class DatasetMeta(namedtuple('DatasetMetaBase', ['dataset', 'num_classes', 'shape'])):

，当您从train.train.DatasetMetaBase生成的第一个文件中删除train.train块时，应该可以清楚地看到丢失的引用是sphinx-apidoc。 train.DatasetMeta和train.train.DatasetMeta的文档将参考train.train.DatasetMetaBase；我不知道没有修补自动文档或添加自己的指令的方法。

从这里，我看到一些选择：

（1）将DatasetMetaBase移至__init__.py中未导入的其他模块。例如

from .abstract import DatasetMetaBase
class DatasetMeta(DatasetMetaBase):

通过这种方式，DatasetMeta的自动文档将引用train.abstract.DatasetMetaBase，这在您的情况下应该是唯一的引用。

（2）创建一个单独的rst文件（例如hidden.rst），该文件呈现train.train.DatasetMetaBase的文档，但从主rst隐藏。

# hidden.rst
.. autodata:: train.train.DatasetMetaBase

这足以将train.train.DatasetMetaBase添加到狮身人面像并解决class reference target not found警告。

如何在不重复所有内容的情况下将Sphinx与子包一起使用？

1 个答案: