What is this "generated" option in Sphinx autosummary directive?

Question

I'm using sphinx-apidoc and autosummary extensions to document an API for a library and I'm really unable to understand the purpose of the generated/ option below:

.. autosummary::
   :nosignatures:
   :toctree: generated/

   module.function_1
   module.function_2
   ...

I've seen this is the Sphinx documentation, and in libraries like pandas. I'm using toctree and my API is autogenerating, but I don't understand what generated is. I don't see a folder called generated, and don't know what the advantage/purpose of this is.

Thanks

Answer 1

The "generated" option is the name of the output directory where Sphinx puts automatically generated "stub" .rst files. It does not have to be called "generated"; you can use any name.

When the autosummary_generate configuration variable is set to True, Sphinx generates a .rst file for each entry listed in autosummary directives. For example, if you are documenting a module with several classes, this feature can be used to put the full documentation for each class on a separate page. The autosummary table will contain links to these pages.