8

Is there a way to display a "Classes" list / tab using Sphinx, or to organize the html pages generated to show members by class, classes being visually well separated?

I use Sphinx 1.1.3, an try to document a Python extension (a custom one created with Cython). My problem is that the whole extension is displayed in one single block if I enter the modules tab (which is quite unreadable) and, by the other hand, the "Index" tab merges everything together (which is normal). I would like a per class display (something closer to what Doxygen would do).

Does something like:

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

* :ref:`classindex`  ???

exists?

Thanks a lot.

Delgan
  • 18,571
  • 11
  • 90
  • 141
Gauthier Boaglio
  • 10,054
  • 5
  • 48
  • 85
  • Well, I found a beginning of answer with the extension 'autosummary', but I lose much information when using it, compared to autodoc, and those 2 seems quite disposed to not work together... – Gauthier Boaglio Jan 30 '13 at 19:48
  • Hmmm, epydoc was my way. Sphinx is more designed to build hand made documentation. – Gauthier Boaglio Jan 31 '13 at 01:07

1 Answers1

9

The autosummary extension, with the autosummary_generate configuration variable set to True, can be used to 1) generate compact summary listings and 2) generate class documentation with one page per class.

You have to explicitly specify each class to be included, but once this is done you have a setup for generating clear documentation where the classes are visually well separated.

The following markup will output one "stub" .rst page for each class (Class1, Class2, Class3). Each page is based on a template and includes an .. autoclass:: directive that extracts the full documentation. In the final HTML output, each class page is linked from the corresponding entry in the main autosummary table. 

:mod:`mymodule` --- Some module
===============================

This module contains several classes. 

.. currentmodule:: mymodule

Class overview
--------------

.. autosummary::
   :toctree: stubs
   :template: class.rst

   Class1
   Class2
   Class3

Details here: https://www.sphinx-doc.org/en/master/usage/extensions/autosummary.html

jak123
  • 318
  • 2
  • 12
mzjn
  • 48,958
  • 13
  • 128
  • 248
  • 1
    In 2020, is there a way to make Sphinx detect all the classes automatically instead of having to add them manually. For me the whole point of having a documentation generator to avoid having to update a template for the documentation that needs to be kept in sync with the source code. – rraallvv Aug 14 '20 at 22:24
  • Maybe this is what you are looking for: https://stackoverflow.com/a/62613202/407651 – mzjn Aug 15 '20 at 05:17