search

astropy / sphinx-automodapi

Sphinx extension for generating API documentation
https://sphinx-automodapi.readthedocs.io
BSD 3-Clause "New" or "Revised" License
62 stars 45 forks source link

No member information generated for exceptions #162

Open rra opened 1 year ago

rra commented 1 year ago

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 commented 1 year ago

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 commented 1 year ago

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:

https://github.com/astropy/sphinx-automodapi/blob/6e476f21476949d3b71dc9df19ab4feb191ac803/sphinx_automodapi/automodsumm.py#L500

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 commented 1 year ago

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 commented 2 weeks ago

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