No member information generated for exceptions

[rra]

I'm working on a code base that often defines methods (both class and instance) on exceptions. The class methods are used to construct the exception from other data (often other underlying exceptions), and the instance methods are used to format the exceptions for reporting to external systems.

It looks like sphinx-automodapi doesn't generate method information for exceptions, and I didn't see any documented way to enable this. For example, an exception class with a to_slack instance method and a from_exception class method generates only:

SlackWebException
=================

.. currentmodule:: safir.slack.blockkit

.. autoexception:: SlackWebException

I was hoping there would be some way to enable the normal sort of class documentation, such as:

SlackWebException
=================

.. currentmodule:: safir.slack.blockkit

.. autoexception:: SlackWebException

   .. rubric:: Methods Summary

   .. autosummary::

      ~SlackWebException.from_exception
      ~SlackWebException.to_slack

   .. rubric:: Methods Documentation

   .. automethod:: from_exception
   .. automethod:: to_slack

[pllim]

According to https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#directive-autoexception , it "will by default only insert the docstring of the object itself". If you want methods includes, you have to provide extra directives. That is from Sphinx proper, I don't think this is strictly related to sphinx-automodapi ? I could have misunderstood your problem though. Can you please clarify? Thanks!

[rra]

The second example in my bug report is the rST code that sphinx-automodapi generates for a regular class, so I don't think it's relying on any special support in Sphinx for generating the method summary. It's generating rST specifying which methods for which to generate documentation.

What I would like it to do is the same thing for exceptions. Currently, apparently exceptions are special-cased to not get the method summary of other classes.

I suspect the problem may be that there is no template for exceptions, and therefore the code here:

sphinx-automodapi/sphinx_automodapi/automodsumm.py

Line 500 in 6e476f2

tmplstr = 'autosummary_core/%s.rst'

falls back on the base template, which doesn't include a method summary. I would get the behavior that I want if a template like the class template were used instead, I think (although there are probably complications that I'm not yet seeing). Although I'm not 100% sure I found the correct code, since the rST generated for an exception doesn't quite match any of the templates.

[pllim]

We currently do not have resources to maintain this much, so if you really want this fixed, feel free to submit a PR, or not use automodapi for that section. Thanks!

[parejkoj]

I'll ping this one, as I also have a custom exception with documented methods that don't show up in our output docs because of this:

This docstring and method:

https://github.com/lsst/pipe_base/blob/fe85a52a0f82f086f2117950cdcd6b2501af1b7c/python/lsst/pipe/base/_status.py#L165

doesn't appear here in the output docs here:

https://pipelines.lsst.io/v/daily/py-api/lsst.pipe.base.AnnotatedPartialOutputsError.html

[parejkoj]

I'm trying to fix this here: https://github.com/parejkoj/sphinx-automodapi/tree/support-exception-classmethod

[bsipocz]

@parejkoj - do feel free to open a PR, if it passes tests and looks good I'm happy to go ahead to merge and release, but looking into other people's branches outside of PRs is not really a workflow any of us can dive into.