Using sphinx for very basic structure

Question

This is my file hierarchy:

InfoRescue
|
|_ src
|
|_ _ _ includes
|
|_ _ _ _ _ i1.py
|_ _ _ _ _ i2.py
|_ _ _ _ _ init.py
|
|_ _ _ utils
|
|_ _ _ _ _ u1.py
|_ _ _ _ _ u2.py
|_ _ _ _ _ init.py
|
|_ _ _ doc
|
|_ _ _ _ _ index.rst
|_ _ _ _ _ project.rst
|_ _ _ _ _ contact.rst
|_ _ _ _ _ api
|
|_ _ _ _ _ _ _ api.rst
|_ _ _ _ _ _ _ includes.rst
|_ _ _ _ _ _ _ utils.rst

I am using Sphinx to generate the documentation. Everything related to sphinx is in doc directory.

My index.rst:

.. InfoRescue documentation master file, created by
   sphinx-quickstart on Sun Sep 15 13:52:12 2013.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

Welcome to InfoRescue's documentation!
======================================

Contents:
========

.. toctree::
   :maxdepth: 2

   project
   api/api
   contact

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

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

api.rst:

InfoRescue API
**********

.. toctree::
    :glob:
    :maxdepth: 1

    **

Now inside the utils there are to .py files. Both of these files contain no class and direct code, both only contain functions. To document a function I can use .. autofunction:: utils.u1.functionName. This is working correctly but I have to write like this for every function. Is there any short way to simply include all the functions?

Suppose both files in includes directory contain no class and function only some (direct) code. How to generate document for it i.e. which auto-directive to use ?

Also both the init.py files inside the utils and includes directory are empty. I made those two so that I can access the files inside those directory from .rst files. Is there any other approach so that I don't have to create _init_.py files?

Answer 1

There is a default extension for Sphinx called autosummary which has the ability to scan your source code and automatically generate the Sphinx input files containing the necessary autofunction directives.

Answer 2

For the (direct) code, you need to provide that documentation in the first docstring of the file.

Answer 3

Presence of the "__init__.py" file marks the directory as a Python package. You don't need to do that for Sphinx. Instead, you can place the directory contents on the Python path by editing the "src/doc/conf.py" file, adding line(s) after the "import sys, os" line such as:

sys.path.insert(0, os.path.abspath(os.path.join('..', '..', 'utils')))
sys.path.insert(0, os.path.abspath(os.path.join('..', '..', 'includes')))

Of course, if you place docstrings into both "utils/__init__.py" and "includes/__init__.py" and try to document them both using Sphinx with these path additions, then you will have to do more work.

Answer 4

autosummary generates a table

You may rather wish to use something like automodule in your .rst file:

.. automodule:: i1
   :members:

Answer 5

Improving the answer above of @BarryPie, and having this problem of having to add all the sys.path.insert for all the subpackages, I'm using this code in my conf.py :

for root, dirs, files in os.walk('../../src'): # path to my source code
    if '__pycache__' not in root: #__pycache__ folder excluded
        sys.path.insert(0, os.path.abspath(root))

and all the subpackages are imported as requested.