how to make apidocs use packages instead of modules in sphinx-apidoc

Question

I'm using docstrings to document python code and sphinx-autodoc to generate apidoc HTMLs. The structure of my packages is as follows: mainpackage.subpackage.module, I want apidocs to link to classes from a module as mainpackage.subpackage.Class and not mainpackage.subpackage.module.Class. My problem comes from the scikit-multilearn project, for example: I have an MLClassifierBase class in skmultilearn.base.base, but I'm importing it in __init__.py in skmultilearn.base, and I want the sphinx-generated apidocs to only use this class as skmultilearn.base.MLClassifierBase and not skmultilearn.base.base.MLClassifierBase as it does now. Can someone help?

I've already tried:

• set add_module_names = False in conf.py per Sphinx apidoc - don't print full path to packages and modules

• added """.. automodule:: base""" to skmultilearn/base/__init__.py

• added __all__ = ['MLClassifierBase'] to skmultilearn/base/__init__.py

• added .. autoclass:: base.MLClassifierBase to the class docs

I'm still having a Bases: skmultilearn.base.base.MLClassifierBase in every class that derives from MLClassifierBase. How do I change this?

Answer 1

I have found a solution:

"""
The :mod:`skmultilearn.base` module implements base
classifier classes for scikit-multilearn's multi-label classification.
"""

from .base import MLClassifierBase
from .problem_transformation import ProblemTransformationBase

__all__ = ["MLClassifierBase", 
           "ProblemTransformationBase"]

It produces documentation for base.ProblemTransformationBase and not base.base.ProblemTransformationBase. You need to have the three elements alltogether in your __init__.py:

• the definition of :mod: mentioned anywhere
• the imports of classes
• the names of classes in `all``