Clean-up API doc commented out due to Sphinx 2.1

[pllim]

In #8786 , some API doc were commented out. When astropy/sphinx-automodapi#82 is addressed, we need to come back to the commented doc and do something about them.

[bsipocz]

Or, we can decide to have API ref list strictly in one place, as @astrofrog suggested: #8786 (review)

I feel I could argue both ways, but it's all theoretical as currently we cannot have them at multiple place and someone needs to feel very strongly about it so they implement the workaround for it in sphinx-automodapi.

[pllim]

Maybe @mwcraig and @mhvk have opinions, given they are lead maintainers for the affected sub-packages?

[mwcraig]

I lean towards having links from multiple places, though if we had them in one standard place in each astropy subpackage I could live with that. No strong feelings either way, really.

[mhvk]

Looking at the units.logarithmic stuff, I recall thinking it was logical to include it in the description since the API was well-contained, but thinking about it again, I also quite like the idea that everything is on the main page (as long as we can link to the relevant module).

Certainly, I think we generally encourage every useful function/class to be on the top level of a sub-module, with modules below being semi-private (one exception being io, where one can down one level deeper). So, it would make some sense to also document the API in that one place.

The one thing that this prevents is to give some sense of the internal organization - something that is very useful to (prospective) developers. In this respect, I still like @astrofrog's old idea of using the module docstring to lay out the lay-out of each submodule.

[mhvk]

p.s. Bottom line: quite happy to just have the API in one place.

[bsipocz]

I lean towards having links from multiple places, though if we had them in one standard place in each astropy subpackage I could live with that. No strong feelings either way, really.

We can always link back to the main page, all headings under References/API have link anchors.

[mwcraig]

We can always link back to the main page, all headings under References/API have link anchors.

Works for me -- clearly most subpackages don't have indexes in multiple places. Also pinging @larrybradley because he is the lead on nddata.utils

[larrybradley]

@mwcraig That's fine with me too.

[bsipocz]

This has been done in #8807