12

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

bad_coder
  • 11,289
  • 20
  • 44
  • 72
Dashing Adam Hughes
  • 1,522
  • 1
  • 13
  • 12

1 Answers1

8

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.

mzjn
  • 48,958
  • 13
  • 128
  • 248