How to document one file with functions?

python, python-sphinx, sphinx-apidoc

Solution

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:

- Create lib.py

Create documentation folder: `mkdir doc`

├── doc/
└── lib.py

- Enter doc/: `cd doc`

- Execute `sphinx-quickstart` (Be sure to select `autodoc: y`, `Makefile: y`)

- Edit conf.py to specify sys.path: `sys.path.insert(0, os.path.abspath('..'))`

Edit index.rst and specify modules in the toctree:

.. toctree::
    :maxdepth: 2

    modules

- Execute `sphinx-apidoc -o . ..`

- Generate the html output: `make html`

- View your documentation: `firefox _build/html/index.html`

Problem

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?

Original source