python - 如何在不复制所有内容的情况下将 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 为这些包生成以下部分:

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，它们指的是同一件事。删除这些部分中的任何一个都会导致 undefined reference 警告(使用 -n 到 SPHINXOPTS 时会变成错误)。

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

我该如何解决这个问题？

train/train.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]

train/__init__.py

from .train import *

__all__ = ['DatasetMeta']

sphinx/source/conf.py

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 生成的第一个文件中删除 train.train block 时，应该清楚地表明缺少的引用是 train.train.DatasetMetaBase -apidoc。 train.DatasetMeta 和 train.train.DatasetMeta 的文档将引用 train.train.DatasetMetaBase；如果不修补 autodoc 或添加您自己的指令，我不知道如何解决这个问题。

从这里，我看到了几个选项:

(1) 将DatasetMetaBase 移动到未在__init__.py 中导入的不同模块。例如

from .abstract import DatasetMetaBase
class DatasetMeta(DatasetMetaBase):

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

(2) 创建一个单独的第一个文件(例如，hidden.rst)，为 train.train.DatasetMetaBase 呈现文档，但对主要的 rst 隐藏。

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

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