CODEWITHSUNDEEP
pythonpython-sphinx
HuLu ViCa
HuLu ViCa

Reputation: 5450

How to add automodule to Sphinx toctree

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.

Upvotes: -1

Views: 3912

Answers (1)

bad_coder
bad_coder

Reputation: 12880

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.

  1. 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

  1. 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.)

  1. 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

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

    .. toctree::

   self

  2. 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.

  1. You can't add an .. automodule:: as a .. toctree:: entry. (As demonstrated above).

  2. 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:

  1. 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

Upvotes: 1

Related Questions