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?

jcarballo · Accepted Answer · 2013-12-05T00:33:54.197

17

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

edited Dec 05 '13 at 00:33

answered Dec 03 '13 at 15:36

jcarballo

27,395
3
28
28

thanks for your response! Yes, I have selected "yes" for autodoc. If I do _sphinx-apidoc -o_ without adding _modules_ in **index.rst**, it creates **lib.rst** and **modules.rst**, but they are empty. If I add _modules_ in **index.rst** and after I do _sphinx-apidoc -o_: it creates the same **lib.rst** like in 1st case, but there is the IOError: [Errno 5] Input/output error when it tries to create **modules.rst**. – natalia Dec 04 '13 at 13:12
yes, i have saw already your Sphinx guide, and I did almost the same. – natalia Dec 04 '13 at 13:15
I reproduced your scenario and added a step-by-step list, please check if that works. – jcarballo Dec 05 '13 at 00:34
2

Ok! It works! Thank you very much, @jcarballo! In fact, if we add _modules_ in **index.rst**, it needs to precise that all **rst** files must be in the same place where **index.rst** is. So it is better to do _sphinx-apidoc -o_ directly being in the same directoty where the **index.rst** is (in my case it is **source** directory). – natalia Dec 05 '13 at 15:34
Glad it worked! Thanks for your note on the placement of .rst files, I didn't knew about that one. – jcarballo Dec 06 '13 at 16:23

How to document one file with functions?

1 Answers1

Linked