Using sphinx to auto-document a python class, module

Adam Matan picture Adam Matan · Aug 25, 2009 · Viewed 16.9k times · Source

I have installed Sphinx in order to document some Python modules and class I'm working on. While the markup language looks very nice, I haven't managed to auto-document a Python code.

Basically, I have the following Python module:

SegLib.py

And A class called Seg in it. I would like to display the docstrings of the class and module within the generated Sphinx document, and add further formatted text to it.

My index.rst looks like this:

Contents:

.. toctree::
:maxdepth: 2

chapter1.rst

and chapter1.rst:

This is a header
================
Some text, *italic text*, **bold text**

* bulleted list.  There needs to be a space right after the "*"
* item 2

.. note::
   This is a note.

See :class:`Seg`

But Seg is just printed in bold, and not linked to an auto-generated documentation of the class.

Trying: See :class:Seg Module :mod:'SegLib' Module :mod:'SegLib.py'

Didn't help, too. Any ideas or good tutorial links?

Edit: changed SegLib to segments (thanks, iElectric!), and changed chapter1.rst to: The :mod:segments Module --------------------------

.. automodule:: segments.segments

.. autoclass:: segments.segments.Seg

Still, can't get Sphinx to directly document functions within a class, or better - to automatically add all the functions within a class to the document. Tried:

.. autofunction:: segments.segments.Seg.sid

and got:

autodoc can't import/find function 'segments.segments.Seg.sid', it reported error: "No module named Seg"

Any ideas how to auto-document the functions and classes with a short command?

Udi

Answer

iElectric picture iElectric · Aug 25, 2009

Add to the begining of the file:

.. module:: SegLib

Try using :autoclass: directive for class doc.

BTW: module names should be lower_case.

EDIT: I learned a lot from reading other source files.