Automatic links from code examples to reference documentation

Proposal

Hi! I’d like to propose an improvement to urllib3’s documentation. The change would make urllib3’s functions and classes in code examples clickable to take the user to their reference documentation entries. I’ve built the documentation locally for a proof of concept, so here’s the home page example:

It would use the sphinx-codeautolink extension to automatically analyse the examples and produce links.

Context

Full disclosure: I’m the author of said extension. I spent the weekend building a bunch of different Python projects with it and fixed lots of issues. urllib3’s case was very neat though, so I decided to propose this to you directly. The library is in beta, but based on local testing it worked well. Currently the setup is only two lines of code in conf.py: activating the extension and configuring an “import urllib3” to be included before all examples:

extensions = [
    ...,
    "sphinx_codeautolink",
]
codeautolink_global_preface = "import urllib3"

Alternatives / against the change

The current solution of linking the relevant function before every example certainly works quite well especially since the examples are pretty simple, containing very few different functions per snippet! Perhaps some links could be stripped out if this change is adopted though. Also, it could be not entirely obvious that the code examples are clickable, leading to some confusion.

Contribution

I’d be willing to submit a PR for sure, once we figure out the details!

---

What do you think, would it be a good fit? If you don’t like the change, feel free to shoot me down immediately! I recognise this could be just adding some maintenance burden for little gain, but personally I think the links make user experience much better. Also, let me know if you have any questions!

[sethmlarson]

@felix-hilden Yeah! We build our docs on every PR and they can be viewed in a staging environment on RTD.

[felix-hilden]

I think the ping missed me, but anyways, thank you for the kind words!

With his well-thought-out explanation, I think I agree too. But I’d love to help if I can! Your theme is Furo already, so what do you mean? Or simply submitting a PR to see it in action fully?