Turn off the "noindex" in the apidocs?

[dangunter]

In order to find documentation in the apidocs, i.e. when it is not included directly in a webpage, the "noindex" option cannot be present when they are generated.

This has two related side effects:

• Autodoc directives in an RST page will need to include ":noindex:" in their options to avoid warnings
• When you link to a class, module, function, etc. the docs location will be in the apidoc-generated tree (not the documentation page)

The second one is a bit of a kicker, and I think points to a conflict in philosophy that we should resolve.

[lbianchi-lbl]

@dangunter I suspected there could be issues (with, possibly, additional ones introduced by #526).

However, I'm not sure I have a clear idea what the problem looks like on the actual docs pages; or, equivalently, how a "fixed" version should look like. Is there a way you could add e.g. a few screenshots to help me understand better?

[lbianchi-lbl]

Following additional discussion, we agreed to do the following:

• Having sphinx-apidoc generate the index entries
• Convert uses of .. automodule:: in human-authored documents to use reference/links to the indexed entry instead, which should be enough to cover the majority of use cases without requiring :noindex:
• Amend the documentation for using :noindex: to support use cases in which "inlining" .. automodule:: is desired

Therefore, I'm closing #542 (since it goes in the opposite direction) and will open a new PR implementing the desired changes.