How to generate Python package documentation with Sphinx

Question

Currently I do this:

conf.py:

autosummary_generate = True

reference.rst:

package_1
---------
.. autosummary::
   :toctree: _generated

   package_1.module_1
   package_1.module_2
   package_1.module_3
   ...

This will generate an overview table for each module, with entries for each module that nicely link to detail pages.

I have two questions:

Do I really have to enumerate every single module?
How can I control the options of the detail pages?

Ad 1.: I would like to do s.th like this (which currently doesn't work):

.. autosummary:: package_1
   :toctree: _generated
   :members:

(Or maybe a new autopackage command.)

Ad 2.: I would like to pass options like the ones that automodule or autoclass expect, e.g.:

.. autosummary::
   :toctree: _generated
   :undoc-members:
   :private-members:

This seems to be an obvious task, so I am probably missing some information. Is there an easy alternative way to accomplish this?

Have a look at [`sphinx-autogen`](http://www.sphinx-doc.org/en/master/ext/autosummary.html#sphinx-autogen-generate-autodoc-stub-pages) to generate stub pages in rST, from which you would generate your docs. There's a similar toolchain with [sphinx-apidoc](http://www.sphinx-doc.org/en/master/man/sphinx-apidoc.html) and [autodoc](http://www.sphinx-doc.org/en/master/ext/autodoc.html). — Steve Piercy, Apr 15 '18 at 10:18
Similar question: https://stackoverflow.com/q/48074094/407651 — mzjn, Apr 15 '18 at 10:59
@StevePiercy as I understand it, `autosummary_generate = True` is equivalent (http://www.sphinx-doc.org/en/master/ext/autosummary.html#confval-autosummary_generate) — mar10, Apr 15 '18 at 12:08
@mzjn You're right: the question you linked to is similar. It offers a solution to the 'Ad 2.' part of my question. Would you suggest that creating a custom template is the way to go (looks a bit complicated to me, but anyway)? — mar10, Apr 15 '18 at 12:14
@mar10 I don't know what, if any, differences there may be between the two, so I don't know if they are equivalent. Suggest trying both to compare and contrast, as divining the differences from reading documentation is tedious. TBH, this is the first time I've seen sphinx-autogen. — Steve Piercy, Apr 15 '18 at 19:47
@mar10 I can't think of anything else. It is unfortunate that autosummary doesn't accept more options. — mzjn, Apr 16 '18 at 14:42
Thank you all for your time and comments, I summarized my solution in a separate answer. — mar10, Apr 16 '18 at 18:28

score 0 · Answer 1 · answered Apr 16 '18 at 18:27

Thanks to all commenters!

Ad 1:
I list the modules manually.

Ad 2:
I finally went with the solution proposed by this and this answers to similar questions:

Create template files (_templates/autosummary/module.rst and _templates/autosummary/class.rst) and add this to
api_doc.rst:

Package ``wsgidav``
-------------------
.. autosummary::
   :toctree: _autosummary

   wsgidav._version
   wsgidav.compat

How to generate Python package documentation with Sphinx

1 Answers1