Can this package be replaced by something else already in Sphinx?

[pllim]

When this package was written, Sphinx was pretty young. Perhaps it has a built-in feature that can replace this package now; maybe https://www.sphinx-doc.org/en/master/usage/extensions/autosummary.html#sphinx-autogen-generate-autodoc-stub-pages ? Or is this not possible because what Sphinx has is not completely automated?

Simon, "... they have https://www.sphinx-doc.org/en/master/man/sphinx-autogen.html and https://www.sphinx-doc.org/en/master/man/sphinx-apidoc.html, but it's not clear to me what it covers and what is missing."

This would supersede #146

[HealthyPear]

Personally, after dealing with #73 I tried to revert to using native sphinx extensions like autodoc, autosummary, and the 2 CLIs mentioned here, but it's really not the same thing...they do what they say but the overhead is a lot, and the amount of code to maintain increases.

Apart from the great annoyance of #73 this package never let me down, really.

[AA-Turner]

A broader question is what does automodapi do that autodoc / autosummary / apidoc doesn't cover? I'd be happy to upstream the functionality, but I don't use this package so I don't know what changes would be needed in Sphinx.

A

from #219 (comment)

I'd be happy to incorporate parts of this project upstream, but I don't know what is unique here / not covered already upstream. cc @pllim @bsipocz

A

[pllim]

@AA-Turner I am very interested to pursue this but I did not write this package, so either @eteq or @astrofrog can clarify, or someone has to find time to inspect code here and over at Sphinx.

[Cadair]

My understanding of how automodapi works is that it sits between autodoc and apidoc in terms of abstraction. Unlike
apidoc it's up to the author of the documentation to write what modules they want documenting where, but then like apidoc (I think I've never used it) it generates rich documentation for each thing in the module.

automodapi uses slightly customised versions of autodoc and autosummary to generate its output.

I think the first thing to look into upstreaming would be those changes to autodoc and autosummary and the inheritance diagram directives, that would simplify the code here a lot then we could think about moving the automodapi directive later?

[astrofrog]

@AA-Turner - as you asked about what is unique here, I have been experimenting with sphinx.ext.apidoc in the reproject package:

astropy/reproject#572

and here is a preview:

https://reproject--572.org.readthedocs.build/en/572/api/reproject.html

For comparison, the existing docs:

https://reproject.readthedocs.io/en/stable/#reference-api

The main difference is that in general:

• sphinx.ext.apidoc will produce full API documentation for the package and there is not a way to not do this as far as I can tell. With sphinx-automodapi you have a directive to auto-document a single module as @Cadair pointed out

• sphinx-automodapi will produce tables of objects like this:

• sphinx-automodapi will produce one page per object (class or function), which can be more readable for modules with many objects. For reference, sphinx-autoapi has a customizable option for what level of granularity to split up at, which maybe would be something to emulate.

So I think the main big picture thing that would make these more similar would be to have:

• the option to make one page per object (class or function)
• the ability to insert tables of objects into existing pages for objects in a certain module which link to the individual pages - this could be done via a directive like .. automodapi:

Other things related to inheritance diagrams or more specific customization options about what to include etc are nice but just wanted to first highlight some of the big picture things that would be nice to see upstream.