Automagic real-world usage examples, code intelligence (opt-in sourcegraph integration)

[slimsag]

The way doctree ties back to Sourcegraph is that you can opt-in to connecting it to a Sourcegraph server if you like.

Running locally or self-hosting, you can opt-in to connecting it to Sourcegraph.com (free for public code) or a private Sourcegraph instance. The online version doctree.org will be connected to Sourcegraph.com to show off these features. If you choose to, these are the features you'd get as add-ons to the regular doctree experience:

• Automatic real-world usage examples
• Code intelligence (hover/go-to-definition/find-references on function signatures, etc.)
• (far into future) Repo permissions / OAuth / etc., this stuff is very hard/annoying to build and Sourcegraph already has this info in enterprise environments, the idea is if you connect to Sourcegraph it could just "respect" all of that automatically.

Important to note all of these are things we just couldn't afford to add to doctree otherwise from a technical POV (e.g. we need statistical analysis of a large corpus of code to find good usage examples, integrating with tons of code hosts & respecting repository permissions is super technically challenging, etc.) so the idea is that everything here is synergetic, and truly just an add-on that can make the experience better.

We want doctree to be respectful of privacy, especially on local / private code, so this will be opt-in. If you want to use doctree standalone without any external service, that's a 100% valid use case we want to support. First and foremost, doctree should be a useful standalone tool - these are just optional add-ons.