gh-87378: [doc] Link to source

[verhovsky]

Links to source of classes and functions defined in Python or using the Argument Clinic using sphinx.ext.linkcode (available since Sphinx 1.1)

https://bugs.python.org/issue43212

• Issue: Link to class and function source code on GitHub #87378

[verhovsky]

Looks like this (functions that don't span 2 lines look a bit nicer)

and links to this

[verhovsky]

You can test what this extension links each name to by pulling my fork

git clone git@github.com:verhovsky/cpython.git
cd cpython
git pull
git checkout link-to-source
cd Doc

then uncommenting the last 2 commented out print() lines in Doc/tools/extensions/link_to_source.py and building the documentation like this:

rm -rf build/*
make html | tee >(grep -v "\s" > doesnt-exist) | tee >(grep -v "\.\.\. ." | grep "\s" > exists)

creating two files exists and doesnt-exist which will contain functions it could and couldn't find a link to source for, which will look like this:

asyncio.Task.get_coro                                                  Lib/asyncio/tasks.py                          132       def get_coro(self):
asyncio.Task.get_name                                                  Lib/asyncio/tasks.py                          135       def get_name(self):
asyncio.Task.set_name                                                  Lib/asyncio/tasks.py                          138       def set_name(self, value):
asyncio.coroutine                                                      Lib/asyncio/coroutines.py                     105   def coroutine(func):
asyncio.iscoroutine                                                    Lib/asyncio/coroutines.py                     177   def iscoroutine(obj):
asyncio.iscoroutinefunction                                            Lib/asyncio/coroutines.py                     164   def iscoroutinefunction(func):
asyncore.loop                                                          Lib/asyncore.py                               192   def loop(timeout=30.0, use_poll=False, map=None, count=None):
asyncore.dispatcher                                                    Lib/asyncore.py                               210   class dispatcher:
asyncore.dispatcher.handle_read                                        Lib/asyncore.py                               479       def handle_read(self):
asyncore.dispatcher.handle_write                                       Lib/asyncore.py                               482       def handle_write(self):

Currently 5058/9079 documented symbols would have a link to source:

$ wc exists doesnt-exist 
  5058  31742 813825 exists
  4021   4015  96125 doesnt-exist
  9079  35757 909950 total

Some reasons for stuff not getting linked:

1. objects defined in C without using the Argument Clinic aren't detected
2. since we don't look at what happens in __init__() we don't have a source for most class variables, this doesn't really matter if the class definition is linked to
3. some things are documented with a symbol name that doesn't correspond to the code, for example asyncio.loop.* is actually asyncio.AbstractEventLoop.* or asyncio.BaseEventLoop.*
4. only top level import statements are processed, imports in if statements aren't picked up

This adds about 5 seconds to make html on my laptop, about 8% longer.

[github-actions]

This PR is stale because it has been open for 30 days with no activity.

[ghost]

All commit authors signed the Contributor License Agreement.

[erlend-aasland]

cc. Sphinx experts @AA-Turner and @hugovk

[AA-Turner]

Thanks for the ping @erlend-aasland -- from my perspective this PR needs several architectural changes (not doing things in the module scope, at the least) -- likely larger than what can reasonably be achieved via the GH suggestions mechanism, so unless anyone objects I'd propose to push my suggested changes to this branch?

A