#StackBounty: #python #python-3.x #python-sphinx How can I use Sphinx with subpackages without duplicating everything?

Bounty: 50

I have the following package structure as a minimal example (for convenience, all is uploaded here):

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

When writing Python packages, one must specifiy the __all__ constant in the __init__.py of any package in order for Sphinx to be able to map a reference such as train.DatasetMeta to train.train.DatasetMeta or similar. However, sphinx-apidoc generates the following sections for these packages:

train package


train.train module

.. automodule:: train.train

Module contents

.. automodule:: train

Which duplicates the entire documentation as it contains .. automodule:: module.file as well as .. automodule:: module, which refer to the same thing. Removing either of these sections results in undefined reference warnings (turned into errors when using -n to SPHINXOPTS).

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

How can I solve this?


from collections import namedtuple

class DatasetMeta(namedtuple('DatasetMeta', ['dataset', 'num_classes', 'shape'])):
    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 = [

source_suffix = '.rst'
master_doc = 'index'

I just cannot figure out what the logic is here.

Get this bounty!!!

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.