I want to document a Python package using Sphinx. Let's assume the package consists of two modules and has the following structure:
my_package
__init__.py
mod_a.py
class_a_1
class_a_2
mod_a.py
class_b_1
class_b_2
To make all classes available to the user at the package level, the __init__.py
contains the following lines:
from .mod_a import class_a_1, class_a_2
from .mod_b import class_b_1, class_b_2
Currently, I generate an API documentation of my classes using an rst file with the following lines:
.. automodule:: my_package.mod_a
:members:
:undoc-members:
.. automodule:: my_package.mod_b
:members:
:undoc-members:
In the resulting documentation the classes are listed e.g. as:
class mypackage.mod_a.class_a_1
Question 1
How can I get Sphinx to list the classes in the following two ways:
class class_a_1
or:
class my_package.class_a_1
In addition to the API reference, I want to add a tutorial which contains references to the classes and some of their methods. Currently, the following rst references work:
.. currentmodule:: my_package.mod_a
:class:`class_a_1`
or:
:class:`my_package.mod_a.class_a_1`
Question 2
Is there a way of referencing the classes and methods without defining the full module structure and without using the .. currentmodule::
directive? In the documentation I often have to switch between the classes from different modules and want to avoid a lot of .. currentmodule::
directives. Ideally, I would like to use the following ways of referencing:
This sentence uses a references to :class:`class_a_1`
and :class:`class_b_1`
. Alternatively, it would be nice if I could write :class:`my_package.class_a_2`
and :class:`my_package.class_b_2`
.
Question 3
I want the package to look flat to the user with all classes in the main namespace. Is there anything I could add to my Sphinx documentation file or to the __init__.py
in order to be able to generate the API doc with a single command like
.. automodule:: my_package
:members:
:undoc-members:
Currently, this command produces an empty page.
Thank you very much!