Module-level variable "docstrings" not picked up

[cdeil]

@mhvk - I see you've implemented an option to add module-level variables to automodapi in #24 . This is something I've wanted for Gammapy for a long time, thank you!

One question I have is how one should document those variables. In the test case you add in #24 you have

PARROT_STATE = 'dead'
"""The global state of the parrot."""

and I would have expected """The global state of the parrot.""" to show up in the HTML docs. But instead this is shown: str(object=’‘) -> str. So apparently PARROT_STATE.__doc__ is used directly.

What should we do here? Change Sphinx to find and use the string following the variable in the output? Or just write "variable docstrings" like this?

PARROT_STATE = 'dead'
PARROT_STATE.__doc__ = """The global state of the parrot."""

Whatever decision is made, I think this should be mentioned in the docs, and maybe even the test should be changed to make sure PARROT_STATE.__doc__ is picked up correctly by Sphinx.

cc @astrofrog - Maybe you have an opinion here as well?

[cdeil]

It's weird. In this case the "docstring" is picked up currently:

source_catalogs = SourceCatalogRegistry.builtins()
"""Registry of built-in catalogs in Gammapy.
The main point of the registry is to have one point that
knows about all available catalogs and there's an easy way
to load them.
"""

https://github.com/gammapy/gammapy/blob/5eee87fce1d5c2e9db88d7284a967dd765bae020/gammapy/catalog/registry.py#L116

So it works for some types of objects, but not built-in ones like str or OrderedDict?