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

Question

我将以下包结构作为最小示例(为方便起见,所有内容都在此处上传):

.
??? sphinx
?   ??? build
?   ??? Makefile
?   ??? source
?       ??? conf.py
?       ??? index.rst
?       ??? train.rst
??? train
    ??? __init__.py
    ??? train.py

当写Python包,必须specifiy的__all__在恒定__init__.py任何包装的,以便斯芬克斯能够参考映射如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相同的内容.除去或者在未定义参考警告这些部分结果(使用时变成错误-n到SPHINXOPTS).

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

我怎么解决这个问题？

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

火车/ __ init__.py

from .train import *

__all__ = ['DatasetMeta']

斯芬克斯/源极/ 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'])):

这应该很明显，当您从 . 生成的第一个文件中train.train.DatasetMetaBase删除该块时，缺少引用。和的文档将参考；我不知道如何在不修补 autodoc 或添加您自己的指令的情况下解决这个问题。train.trainsphinx-apidoctrain.DatasetMetatrain.train.DatasetMetatrain.train.DatasetMetaBase

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

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

from .abstract import DatasetMetaBase
class DatasetMeta(DatasetMetaBase):

这样， autodoc 的DatasetMeta引用train.abstract.DatasetMetaBase，这应该是您的情况下的唯一引用。

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

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

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