0

Problem

I am using sphinx.ext.autosummary for my python package. The problem is that .. autosummary:: adds .. automethod:: __init__ at all times, even if undocumented.

In the mean time I have found various ways to include it a third time (as a special member) or included it in the methods; but not how I can get rid of .. automethod:: __init__.

rst creted by .. autosummary:: (left), rendered HTML documentation (right).

As shown this simply duplicates the class specification above and has no use at all. I could, of course, create all *.rsts by hand but that is not an option and would make autosummary somewhat obsolete. In addition it creates warnings due to duplicate object description (__init__ is in methods as well which is fine).

System

  • python 3.8.5
  • sphinx-build 4.0.2 (w/ bootstrap theme)

Does anyone have the golden hint I am searching for since hours? :)

Thanks a lot in advance!

Reto Stauffer
  • 89
  • 10
  • 1
    Have you looked at the conf.py config values? I'm guessing at your setup a bit but I think this might help: https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#confval-autoclass_content – morric Jun 09 '21 at 10:18
  • 1
    Thanks @morric for the fast reply. I've tested this in all variations, unfortunately `autoclas_content` seems to have no effect on the output of `.. autosummary::`. – Reto Stauffer Jun 09 '21 at 13:03
  • 2
    You can customize the template (class.rst) that is used to generate the "stub" .rst page. See https://www.sphinx-doc.org/en/master/usage/extensions/autosummary.html#customizing-templates and https://stackoverflow.com/q/28147432/407651 – mzjn Jun 09 '21 at 15:53
  • Thanks a lot! Added a possible solution to the original post above. – Reto Stauffer Jun 10 '21 at 08:36

1 Answers1

1

Solution

In the templates_path (see conf.py; typically "_templates") create a folder autosummary. Search for the default class.rst, copy it into the new folder (_templates/autosummary/class.rst) and adjust the template to your needs. Nothing else required.

My adjustments to class.rst

  • After .. autoclass:: {{ objname }} adding :noindex:.
  • Removed line .. automethod:: __init__.
  • Need to figure out if :noindex: as default is a good idea.

Many thanks to @mzjn, that was the hint I missed; saved my day!

Reto Stauffer
  • 89
  • 10
  • Where can I find the default class.rst? – Astral Cai Mar 07 '23 at 21:52
  • @AstralCai Run `import sphinx.ext.autosummary` and look at `sphinx.ext.autosummary.__file__`. That will tell you the install folder. On my machine its something like `/path/to/venv/lib/python3.8/site-packages/sphinx/ext/autosummary/__init__.py`. In the `autosummary` folder, there will be a path `templates/autosummary` which has the default `base.rst`, `class.rst` and `module.rst` templates – Mad Physicist Jul 28 '23 at 16:35