Teach sphinx about the difference between object public names and private names, to enable source links, etc.?

[kaldown]

This is an example from the same documentation engine in Tornado.

It may be useful.
Personally, helped me a lot with other projects.

[njsmith]

Hmm, in theory this is pretty easy to do – there's a sphinx configuration option that you can toggle on.

But, there is a technical issue: I think it doesn't currently work for most of Trio's code, because we hack the metadata in all our public functions and classes to contain the public name they're exposed under (ref) instead of the private name they're created under. But I'm pretty sure sphinx needs to know the private names to find the source. I haven't actually double-checked this recently, so I could be wrong. And this could be fixed with sufficient hacking.

More generally: I'm not sure whether source links are helpful or not? On the one hand, reading the source can be really useful, and it's not like we're trying to hide it or anything. OTOH, it does add more clutter to the documentation pages, and I worry a bit that it'll nudge folks into using private APIs.

I am probably the single worst person to judge this though, because I am the one Trio user who never learned it from the docs :-). So, what does everyone think? Would source links in the docs be helpful, and worth fighting with sphinx over?

[oremanj]

Yep, fixup_module_metadata() breaks source links, autodoc_member_order="bysource", and attribute docstrings, all of which rely on Sphinx's Python source code analyzer. A half day or so of mucking with Sphinx did not find a sufficient workaround the last time I tried. I had been using something like fixup_module_metadata() for a work project, and this issue led me to abandon it, although we didn't have anywhere near the same "better hide the implementation details" constraints that a project like Trio does.

We could skip fixup_module_metadata when imported under Sphinx; Sphinx does have a concept that the public name of an entity might be different from its source name. Unfortunately, intersphinx references and :show-inheritance: use the source name. We can't win! (Except by changing Sphinx.)

I do think it's worth leaving this issue open, since improving Sphinx in this way would benefit us, but it's not a trivial fix.