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