Sneak peek: API documentation generated for all your code
UPDATE Nov 10, 2022: Sourcegraph has de-prioritized work on this feature at this time and it has not graduated beyond experimental status. If your team is interested in this functionality, please reach out.
At Sourcegraph, we have a small team working hard on a new experimental feature: API docs.
In order to build awesome code search we've built a global graph of code that has a deep, semantic understanding of the underlying code—which we represent as LSIF code intelligence data. Using Sourcegraph's LSIF code intelligence data, we can analyze your code and generate API documentation for all of it. We've started with Go code and intend to expand to more languages as we develop this feature.
If you develop in Go, Rust, or Zig you’re probably familiar with some sites that try to do this like pkg.go.dev, docs.rs, etc. The benefit of Sourcegraph's API docs over these will in the future be:
- Surfacing usage examples from open source code.
- Providing a single tool that works across all code, using LSIF data to provide an experience tailored towards your languages of choice.
- Giving an amazing navigation and search experience.
Try it (experimental)
Today, it's still in its very early stages—and only a few months into development. But you can try it out on Go code today:
Want to try it out on your own Go repositories? Tweet @sourcegraph with your GitHub repository name and we'll set it up for you, or follow our documentation.
On by default, for everyone
The most important announcement here is that API docs is now an on-by-default experiment for everyone! You can begin trying it out on Sourcegraph.com as well as your own Sourcegraph instance.
Understands the types of symbols, and uses iconography to communicate
API docs is built on code intelligence data, so it has a deep semantic understanding of symbols, their type information, whether they're deprecated, a function, variable, interface, etc., and the UI now communicates this information using icons:
A deep understanding of code
We're paying attention to the small details, and really tailoring API docs to each language.
At Sourcegraph, we use primarily Go and TypeScript—so we're starting by building an experience that Go developers will love, then we'll expand to more languages and build an experience that is really tailored to, and makes sense in the context of, the individual language.
One way we've enabled this is by allowing LSIF language indexers to emit data in the way they see fit. Sourcegraph merely renders it, indexes it, and adds a nice navigation experience.
API docs is still very early in development, so we're making it as easy as possible to give feedback. In fact, we're making it possible to email feedback directly to the lead engineer (that's me) email@example.com—I'm eager to hear what you think!
We've also made it possible to submit feedback on the API docs pages themselves,and you can also send feedback to us via Twitter @sourcegraph.
About the author
Stephen Gutekanst is one of Sourcegraph's earliest engineers, and has authored many parts of Sourcegraph including the
src CLI, monitoring architecture, managed instances, and editor extensions to name a few. Stephen has worked with most of Sourcegraph's largest customers, and enjoys solving the most critical and technically challenging issues users face in our effort to bring world-class developer tools to everyone. Outside of Sourcegraph, Stephen researches and develops search engine and video game technology.
Special thanks to Rebecca Dodd and Erica Lindberg for their help with the content of this article, and Jean du Plessis and the rest of the team for their assistance and feedback on API docs.