API doc tweaks [skip ci]

[gavinmacaulay]

Changes in this PR:

• use automodule (from the autodoc plugin) instead of the automodapi plugin to make the API docs
• add documentation for colormap

These changes are a bit more opinionated than my earlier doc PRs, so I give some context:

I've always found the echopype API documentation hard to follow, mainly because there were two ways to access the individual class/function documentation - the long unsorted list of function/member names under the API reference menu in the left sidebar of the docs and the same stuff under various headings in the right sidebar with a confusing Functions entry under each heading.

The changes in this PR remove the list of functions in the left sidebar and the Functions headings in the right sidebar. To me, at least, this makes for cleaner API docs that are also easier to look through for the class/function documentation that one is after.

I also noticed that the echopype-provided colormaps were only documented in the user guide part of the docs and not in the API part, so I added a colormap section with an enhanced docstring.

Using the Sphinx autodoc plugin instead of automodapi removes the etoc.toctree warning that is unavoidable when using automodapi with an external table of contents, so suppression of those warnings is also removed (resolves a comment in #1763). Automodapi is not actively developed compared to autodoc (see Development status in the readme), so not using it reduces potential future hassles.

These sort of changes to the API docs are what I was planning to attempt during the 2026 WGFAST echopype hackathon but never managed to do 😄.

[LOCEANlloydizard]

note because I'm thinking of this now and I have a feeling it's related to this issue re API doc, but I'll dig in a bit later! #1690

[leewujung]

Hey @gavinmacaulay : Thank you SO much for this thoughtful PR! We've not had much time to keep the docs up to date, so your work over multiple PRs is really really appreciated.

I've always found automodapi to be hard to configure, so I am glad that you have changed the docs to use automodule.

I've added a couple small inline comments. Otherwise I think this is ready to go!

Also a note that I think it would be useful to create a very slim package that is only for echogram colormaps, so that it can be called in echopype and used separately. For example, in echoshader (which we haven't had time to update at all for a while...), right now the ek500 colormap definition is actually duplicated. There is EchogramColorSchemes from Blackwell et al. 2019, but perhaps it's useful to just have a simple python duplication?

Thought?

[gavinmacaulay]

I would find a slim Python package for matplotlib colormaps very handy. Alternatively, there are some existing colormap packages (e.g., cmocean, cmasker, colormap) that one could contribute to.

[leewujung]

Thanks @gavinmacaulay! I'll merge this now.

It would be nice to contribute to existing libraries as you said. Perhaps cmocean would be a good fit since it's ocean/earth science-focused. The latest release was 2 years old, so hopefully they are actively maintaining it.