How can I use Sphinx with subpackages without duplicating everything?

557 views

Skip to first unread message

rasmusdie...@gmail.com

unread,

Aug 17, 2018, 10:37:30 AM8/17/18

to sphinx-users

As posted here: https://stackoverflow.com/questions/51881692/how-can-i-use-sphinx-with-subpackages-without-duplicating-everything?

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
=============

Submodules
----------

train.train module
------------------

.. automodule:: train.train
    :members:
    :undoc-members:
    :show-inheritance:


Module contents
---------------

.. automodule:: train
    :members:
    :undoc-members:
    :show-inheritance:

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?

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'