How to add automodule to Sphinx toctree

Question

I want the left menu of Sphinx documentation to have the modules of my project, and I want to define this content from the __init__.py file of the main module. This is what I am trying:

__init__.py
'''
Components platform:
--------------------

* language: python
* rest framework: flask-restful
* testing: pytest
* documentation: sphinx

.. toctree::
   :maxdepth: 1
   :caption: Contents:

   .. automodule:: sacbeh.main

   .. automodule:: sacbeh.api

   .. automodule:: sacbeh.controllers
'''

The problem is that when I run make html, I get these errors:

/Users/hugovillalobos/Documents/Code/sacbeh-project/sacbeh-backend/sacbeh/__init__.py:docstring of sacbeh:9: WARNING: toctree contains reference to nonexisting document '.. automodule:: sacbeh.main'
/Users/hugovillalobos/Documents/Code/sacbeh-project/sacbeh-backend/sacbeh/__init__.py:docstring of sacbeh:9: WARNING: toctree contains reference to nonexisting document '.. automodule:: sacbeh.api'
/Users/hugovillalobos/Documents/Code/sacbeh-project/sacbeh-backend/sacbeh/__init__.py:docstring of sacbeh:9: WARNING: toctree contains reference to nonexisting document '.. automodule:: sacbeh.controllers'

I haven't found a way to achieve this.

EDIT

I know it doesn't work the way it is. I have made it work using rest files, but I am trying to find a way of documenting my project with the least amount of extra files possible, so I want to use docstrings the most possible.

I believe my question is valid, but not necessarily feasible.

`toctree` entries must be .rst files. `.. automodule:: sacbeh.main` is not an .rst file. — mzjn, Apr 13 '21 at 04:34
Also do not use `toctree` in a docstring. It should be used only in reST files. — Steve Piercy, Apr 13 '21 at 04:36
Perhaps you can use `autosummary` with the `recursive` option. See https://stackoverflow.com/a/62613202/407651. — mzjn, Apr 13 '21 at 15:47
Thank you, @mzjn, for being helpful and not critical. I'll check your link to see if it helps me to achieve my goal. — HuLu ViCa, Apr 13 '21 at 15:49
@HuLuViCa I checked your edit and I considered the same issues you mention when I started with Sphinx (I also tried putting the toctree inside the `__init__.py`). The conclusion I arrived at was: keeping the docstring minimal (just parameters + brief description) will save you work in the short-long run. Ok, you use more `.rst` files, but those are easy to refactor, if you have to change the docstrings (instead of the `.rst`) the overhead in work will soon outweigh managing those few extra `.rst` files. — bad_coder, Apr 16 '21 at 01:49

score 1 · Answer 1 · answered Apr 15 '21 at 21:45

Each line in a .. toctree:: directive is called an entry. The entries cannot be autodoc directives.

You have 4 options for the entries:

Entries

Document titles in the toctree will be automatically read from the title of the referenced document.

Simply using the file name as entry without the extension.
```
.. toctree::

   file_name_without_the_rst_extension
```

Entries

(...) you can specify an explicit title and target using a similar syntax to reST hyperlinks

The same as above but specifying a costum title for the entry.

.. toctree::

   Whatever title you want to write <file_name_without_the_rst_extension>

Additional options

You can use “globbing” in toctree directives, by giving the glob flag option. All entries are then matched against the list of available documents, and matches are inserted into the list alphabetically.

(...)

This includes first all documents whose names start with intro, then all documents in the recipe folder, then all remaining documents (except the one containing the directive, of course.)

A glob pattern. Can be the contents of a directory, or all matches for a partial filename.
```
.. toctree::
   :glob:

   intro*
   recipe/*
   *
```

Additional options

The special entry name self stands for the document containing the toctree directive. This is useful if you want to generate a “sitemap” from the toctree. Or

The entry can also be the special name self in which case the .rst containing the toctree is added as an entry.
```
.. toctree::

   self
```
There is one undocumented feature to add an http:// link as an entry using the syntax explained above in point (2.). Check this thread "External Relative Link in Sphinx toctree directive"

Having said that, the problem in the question is incorrect in several ways.

You can't add an .. automodule:: as a .. toctree:: entry. (As demonstrated above).
You shouldn't put a .. toctree:: inside a docstring. This is conceptually wrong, docstrings are used to document the APIs (signature plus brief comment) of the objects they are set on as the __doc__ attribute.

The above is already a lengthy explanation, but what I think really addresses the question is this:

Documenting an __init__.py file would be a rare occurrence. The main reason being, no one using your code/documentation is going to write: from __init__ import something, right?!

What would be the solution? This:

The your_package.rst file (in Python a package is also a module) where you document the classes should look like below. You don't have to put a docstring in the __init__.py, but you do need to have a .rst file corresponding to the package where you put the ..automodule:: directives.

------------
your_package
------------

   .. automodule:: sacbeh.main
      :members:

   .. automodule:: sacbeh.api
      :members:

   .. automodule:: sacbeh.controllers
      :members:

The index.rst where you link the above your_package.rst should look like this:

-----
index
-----

.. toctree::
   :maxdepth: 1
   :caption: Contents:

   your_package

How to add automodule to Sphinx toctree

1 Answers1