In the dev guide module topic python API description, we require the no-main-docstr option, to prevent module docstrings from appearing in the landing page python API section. Having this option set for all our docs prevents us from directly linking to modules using single-backtick links, like we do for classes and methods.
I propose to remove the first paragraph in the callout note in this section, and the :no-main-docstr: from the example above it and all other examples where it is used. We also need a paragraph in the Python API Reference section about what should go into the module-level docstring, linking to the python module docstrings in "Documenting Python APIs with docstrings". Something to the effect of "Python modules should have a short top-level docstring describing the purpose of the module." jsick had suggested to me that module docstrings should be kept short, and might have further suggestions here.
Our existing python module example has a much longer module docstring. Given the guidance from jsick on keeping module docstrings short, I wonder how we would rework that example module? We also have a section on python module docstrings that could be reworded to reflect that a short docstring will be included in the python API docs.
This RFC came out of a discussion on a PR for the verify package, where a commandline interface needed a link to the python module it used. Creating that link means not having no-main-docstr set. For developers, having a short module docstring can be very helpful in understanding the purpose of that file, and I think it's useful to have those docstrings included in the package API docs.