I ended up going with your original suggestion and put the documentation in the packaging (distutils) section.

I think that choice is fine. However you now have duplicated the docstring content because of the difficulty of including it with autodoc.

The linkcode not resolving is an issue that's probably solvable, but I'm not too bothered right now - quite a bit of work for a very minor thing.

@rgommers

I removed the duplication by putting the documentation in an .rst file and reading it when generating __config__.py.

This works and docs look good to me. I have the feeling that this is going to break something though - that file reading doesn't look very robust. It's hard to predict how; for example packaging scripts could be stripping off doc/, which would break the build.

I've seen enough versions now that I've gotten a bit confused - could you remind me why the obvious solution (have the docstring inside generate_config_py, write it from there to __config__.py and adding `show_config` to reference/distutils.rst) didn't work?

The issue was that __config__.py and by extension show are generated during the build process, so Sphinx doesn't know about them prior to building the project.

Isn't this also true of any C function though?

I did stumble upon the add_doc helper for documenting C functions, as well as the convention of writing the function signature as the first line of the docstring.

I'll give these a go today.

I don't think "Sphinx doesn't know about them prior to building the project" is a good argument, as I think this is already true in many other places.

@eric-wieser as I am new to the project's source code, I would appreciate it if you could tell me where to look for something similar in the source, if you can think of such a place.

I'm saying that the suggestion to "have the docstring inside generate_config_py" seems correct to me, as suggested by @rgommers

This pull request is superseded by #15429, so closing.