Fix Version/s: None
Component/s: Stack Documentation and UX
For the Sphinx-based task topic documentation, we want to be able to show the signature of the task's Python API (particularly its _init_ and run methods). This shouldn't replace the canonical source of documentation as generated by automodapi, but it should instead give users a quick summary and entrypoint into that API documentation.
One scenario is to show the signatures of the tasks's constructor and methods, and make those signatures clickable so that a user can access the API docs quickly.
Another approach might be to also show the full docstring of things like the constructor and run method.
The best approach is TBD.
- relates to
DM-15774 Initial Sphinx-based Task documentation for packages
Perhaps we can create a customized Documenter, as in https://github.com/sphinx-doc/sphinx/blob/master/sphinx/ext/autodoc/__init__.py and then create a autoclass-like directive out of that?
It's nice that autoclass has a way of producing API documentation with noindex so it doesn't clobber the noindex made by automodapi.
The problem with this is that we likely want to abbreviate the API documentation that appears task topics.
We really want the task topic to serve as a bridge from the Task landscape to the Python API landscape.
I'm looking into the autodoc APIs to see if there are bits I can pull out. Otherwise we might need to build our own Sphinx extension that generates summaries of Task APIs.