如何在不复制所有内容的情况下使用Sphinx和子包？

Question

我将以下包结构作为一个最小的示例（为了方便起见，全部都上载了here）：

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

在编写Python包时，必须在任何包的__init__.py中指定__all__常量，这样Sphinx才能将train.datasetMeta之类的引用映射到train.train.DatasetMeta或类似内容。但是，sphinx-apidoc为这些包生成以下部分：

^{pr2}$

它复制了整个文档，因为它包含.. automodule:: module.file和{}，它们引用同一个东西。删除这两个部分中的任何一个都会导致未定义的引用警告（在使用-n到{}时会变成错误）。在

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

我怎么解决这个问题？在

训练/火车.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]

训练/初始训练

from .train import *

__all__ = ['DatasetMeta']

狮身人面像/来源/配置文件

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


project = 'test'
copyright = ''
author = ''

version = ''
release = '0'

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

source_suffix = '.rst'
master_doc = 'index'

我就是搞不懂这里的逻辑是什么。在

Answer 1

我们可以做一件事来简化情况，那就是稍微改名：

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

当您从sphinx-apidoc生成的第一个文件中删除train.train块时，应该可以明显地看到缺少的引用是train.train.DatasetMetaBase。train.DatasetMeta和train.train.DatasetMeta的文档将引用train.train.DatasetMetaBase；我不知道如何在不修补autodoc或添加自己的指令的情况下解决这个问题。在

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

（1）将DatasetMetaBase移动到另一个未在__init__.py中导入的模块。例如

^{pr2}$

这样，DatasetMeta的autodoc引用train.abstract.DatasetMetaBase，这在您的例子中应该是唯一的ref。在

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

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

这应该足以将train.train.DatasetMetaBase添加到sphinx并解决class reference target not found警告。在