How to document one file with functions?

Question

I have a python file with functions (lib.py), without classes. Each function has the following style:

def fnc1(a,b,c):
    '''
    This fonction does something.

    :param a: lalala
    :type a: str
    :param b: hahaha
    :type b: int
    :param c: hohoho
    :type c: int

    :rtype: int

    '''

    print a
    d = b + c

    return d

I just want to document each function (inputs and outputs) with Sphinx.

After doing sphinx-quickstart, I defined the path in conf.py with my lib.py. But the output HTML file (welcome page) is empty.

If I write myself in index.rst:

.. function:: func1(a,b,c)
    This fonction does something.

    :param a: lalala
    :type a: str
    :param b: hahaha
    :type b: int
    :param c: hohoho
    :type c: int
    :rtype: int

it is ok, it shows the inputs and outputs in html file. But how to do it automatically?

Normally, I think, it must to do it in lib.rst after doing sphinx-apidoc -o, but in lib.rst there is only:

lib module
==================

.. automodule:: lib
    :members:
    :undoc-members:
    :show-inheritance:

Can somebody explain me step by step what I must do exactly?

Answer 1

First, when you run sphinx-quickstart, be sure you select autodoc:

autodoc: automatically insert docstrings from modules (y/N) [n]: y

Then, in the generated index.rst I usually add modules to include all the modules automatically (watch identation).

.. toctree::
   :maxdepth: 4

   modules

After this sphinx-apidoc -o does generates documentation for me.

I wrote a guide to use Sphinx for Python code used in embedded systems, but the first steps of the Guide might be useful to you as well:

How to generate sphinx documentation for python code running in an embedded system

[EDIT]

Here is a step-by-step list:

1. Create lib.py

2. Create documentation folder: mkdir doc

   ├── doc/
   └── lib.py
   

3. Enter doc/: cd doc
4. Execute sphinx-quickstart (Be sure to select autodoc: y, Makefile: y)
5. Edit conf.py to specify sys.path: sys.path.insert(0, os.path.abspath('..'))

6. Edit index.rst and specify modules in the toctree:

   .. toctree::
       :maxdepth: 2
   
       modules
   

7. Execute sphinx-apidoc -o . ..
8. Generate the html output: make html
9. View your documentation: firefox _build/html/index.html