1

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!

Olaf
  • 371
  • 2
  • 11
  • Please ask one specific question at a time. – mzjn May 16 '16 at 06:50
  • Question 1 is a possible duplicate of http://stackoverflow.com/q/15115514/407651 and http://stackoverflow.com/q/22096187/407651 – mzjn May 16 '16 at 07:07

0 Answers0