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

时间:2018-08-16 16:34:36

标签: python python-3.x python-sphinx

作为最小示例,我具有以下程序包结构(为方便起见,所有文件都上传了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']

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

1 个答案:

答案 0 :(得分:4)

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

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

,当您从train.train.DatasetMetaBase生成的第一个文件中删除train.train块时,应该可以清楚地看到丢失的引用是sphinx-apidoctrain.DatasetMetatrain.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警告。