Improve support for modules/packages

[sergiocallegari]

I apologize in advance if I have missed something seeking previous discussion on the topic.

I am finding some issues with following the numpydoc style guide wrt modules and packages. The documentation has a section "Documenting Modules" that says:

Each module should have a docstring with at least a summary line.
Other sections are optional, and should be used in the same order as for documenting functions
when they are appropriate

Then, a numbered list of items to be included is provided:

1. summary
2. extended summary
3. routine listings
4. see also
5. notes
6. references
7. examples

With the explicit indication that

Routine listings are encouraged, especially for large modules, for which it is hard to get a good
overview of all functionality provided by looking at the source file(s) or the __all__ dict.

With this, it remains a bit unclear to me how the "routine listings" should be provided. Incidentally, also AI bots are confused and from this documentation end up suggesting that you should have a section entitled "Routine Listings", that is clearly not the case.

The problem is that using the sections "for documenting functions" does not really seem a good match. Functions have params and returns, which modules need not. On the other hand, modules tend to provide Functions, Classes, Module variables and constantes. All this could go under a section named "Attributes", but it seems a bit large as a catch-all.

IMHO, it would be nice if modules could rely on "Classes", "Other Classes", "Functions", "Other Functions" section entries.

Without them, I have noticed that for many packages, modules end up having no sectioning at all in the extended summary (which often results in a text that is not structured enough) or deviating completely from the numpydoc guidelines for modules (which may cause issues with IDES that rely on numpydoc to provide a "rich text" view of the docstrings).