Read the Docs Blog - Posts tagged reference

API v3 is now stable

2021-02-16T00:00:00Z

We are excited to announce that our API v3 has reached a stable release, and is now available for all Read the Docs users. Since we announced the API v3 beta, we have been adding extra functionality and bug-fixing minor issues based on user feedback.

The new API v3 is not a fully replacement (yet!) of API v2, but we highly recommend using API v3 for all the new integrations. API v2 will be deprecated soon, though we don’t have a firm timeline for deprecation. We will alert users with our plans when we do.

New features

We’re excited about the following actions that API v3 makes possible:

Import new projects
Activate a version
Trigger builds
Check build status
Manage redirects

API v3 allows you to easily manage common tasks on your Read the Docs project and organization. These include:

Setting up documentation for a new project
Automating the release of a new version
Pausing a release if you detect a failed build
Automatically create redirects for changes files

If you want to know more about it, please check out the full APIv3 documentation.

Help us make it better

We always love to hear from users about how they are using the API. We want to help you manage your documentation in the easiest and most efficient way possible. Please, feel free to open an issue in our issue tracker if there is a use case we are not covering.

Announcing API v3 Beta

2019-08-27T00:00:00Z

In the last months, we have been working on making our API better. Considering the limitations of our current REST API v2, we decided to make a bigger step forward and create a new API v3, putting the focus on the use cases we heard about from existing users.

Compared to API v2, our new API v3 has some big differences that make it more user-friendly and useful.

These differences includes:

API access requires authentication
Token based API authentication
Read and write
Resource lookup can use project’s slug
Wider resource coverage

Some examples of new queries and actions that will be possible with the API are:

If you want to know more about it, please check out the full APIv3 documentation.

Invite-only beta feature

APIv3 is currently in an invite-only beta state on our community site, https://readthedocs.org. In case you want to test it and give us feedback on it, please email us to get early access.

Based on the feedback we receive from you, we plan to add more features to cover most of the common use cases. Please, help us with your feedback to make the new APIv3 even better!

Read the Docs Public API

2018-08-02T00:00:00Z

Recently, we revamped Read the Docs’ public API. Previously, our latest API (v2) was used by our build processes but not heavily used by outside users.

As part of this process, we put effort into making sure the API is easy to use to access Read the Docs projects, builds, and versions, easier to filter builds and versions by a particular project, and that the documentation is up-to-date.

Deprecation of API v1 and connecting over insecure HTTP

As part of this process, we are formally deprecating support for our API v1. It will be supported through at least January 1, 2019 but we strongly encourage all users to migrate to API v2 at their earliest convenience.

In addition, both API v1 and API v2 allowed connecting over insecure HTTP as opposed to HTTPS. Beginning in January 2019, we will be redirecting requests over HTTP to HTTPS. This will improve security and allow us to add more security related features to the API going forward. For most users, this should be a one line change to connect to the HTTPS version of the API.

Get in touch

We are always interested in the amazing things people create when data is openly shared. In addition, we are always looking in improve our API to enable more projects and mashups. If you use Read the Docs’ public API for your project or there are additional features you’d like to see in it, we would love to hear from you.

Announcing pydoc.io beta

2016-11-17T00:00:00Z

Today we’re excited to announce our latest project: https://pydoc.io. This work was made possible by the MOSS Grant from Mozilla. Thanks to Mozilla for funding our time building this wonderful community resource.

About pydoc.io

Running Read the Docs, we’ve always been proud of the documentation tooling that the Python community has. We prioritize prose over API documentation listings, and generally have a high standard of documentation in our projects.

There are a specific set of use cases that API reference documentation support, and the Python community doesn’t support them well. Tools like http://godoc.org and http://rubydoc.info provide these for others languages, and we now introduce http://pydoc.io as the Python community’s version of that.

What is it?

Pydoc.io will eventually auto-generate API reference documentation for every package on PyPI. Our beta release will support a limited set of packages that we are using for testing. Over time we’ll expand the tooling to automatically support generating docs for any package posted on PyPI.

Reference documentation is wonderful for folks who already know how a library works, and simply want to use it. It’s also great for navigating and understanding the internals of a piece of code. Giving them simple access to nicely rendered API documentation supports using and understanding libraries in a nicer way than reading code. We’re happy to build out these tools, along with the wonderful prose tools we’ve always had with Sphinx itself.

Our progress and some context is tracked in issue 1957.

The tools

This project is built on top of Sphinx at it’s core. On top of that, we’ve layered a few different tools:

sphinx-autoapi which is the tool that takes Python source files and turns them into rST.
- Internally, this uses the pydocstyle AST parser, which we use for a parse-only representation of the Python files.
pydoc.io is a Django application that is the actual web front-end and documentation building code.
sphinx-apitheme is the Sphinx theme that powers the actual API listing pages.

The biggest piece to call out here is the parse-only documentation generation. Sphinx’s autodoc module, and most Python documentation generators rely on importing the code to get docstrings. As we’ve learned with Read the Docs, this is quite impractical for a large set of libraries, including the scientific ecosystem that heavily relies on C libraries. Building and supporting a parse-only API tool makes doc builds faster and more reliable.

We have built on top of the pydocstyle AST, but it looks like we’ll likely have to build out our own AST traversal to retrieve all docstrings and construct declarations that we need to output. We have looked into some of the other AST options in Python, but haven’t decided on what direction we want to go when building our own.

We have put a good deal of work into all these different pieces, but there is still a lot of work to be done.

Give us feedback

This is a very beta release. We have developed a few different sets of tools, and would love your feedback. In particular:

Give us examples of API documentation patterns that you like. We’d like to incorporate powerful patterns into our theme.
Don’t give us feedback on specific design issues with the theme, we’re still working on it!
Let us know if you have ideas about how we can improve the general usability of the documentation
Let us know features that you wish the site had

Thanks

Thanks again to Mozilla, who funded this work. It wouldn’t have been possible without them, and we’re happy they funded the initial development. We’re always looking at ways to make the ongoing maintenance sustainable, so please reach out to us if you’d like to help with our efforts!