Read the Docs Blog - Posts tagged api

Announcing Embed API v3 and sphinx-hoverxref 1.0

2021-12-07T00:00:00Z

We are thrilled to announce the availability of Read the Docs Embed API v3, along with its official client, sphinx-hoverxref 1.0. This work has been possible in part thanks to the the CZI grant we received.

The value of content embedding

As we wrote in our first blog post about sphinx-hoverxref, one of the most powerful features of Sphinx is the possibility of creating cross references to other documentation projects. However, a reader finding several links in a technical documentation might need to open several browser tabs to fully understand the context, resulting in a lot of friction in the form of context switching.

One way of mitigating the problem is to show a small preview in the form of tooltip or modal with the contents of the link. This is where the Embed API and sphinx-hoverxref come in.

sphinx-hoverxref is a Sphinx extension that addresses this problem by adding tooltips on the cross references of the HTML documentation with the content of the linked section. To do so, it inserts a small JavaScript file that calls the Read the Docs Embed API when the user hovers any link. Back in June we announced intersphinx support in sphinx-hoverxref 0.6b1, which allowed users to include modals and tooltips also for cross references to other projects.

sphinx-hoverxref displaying a tooltip including an equation

Some big projects already using it include Tweepy, a Python client for Twitter, and Scrapy, a framework for crawling websites.

Embed API v3 and sphinx-hoverxref 1.0

After some months of work, we are excited to publish v3 of our Embed API, and with it, version 1.0 of sphinx-hoverxref.

Among other things, the new versions allow you to embed content from pages hosted outside Read the Docs. For security reasons, we have an allowlist of such external domains that currently includes Python, NumPy, SciPy, SymPy, and we would like to invite the community to suggest more domains to add.

Other additions and fixes include:

Support for JS and CSS assets in Sphinx 4.1+.
Support for glossary / term and sphinxcontrib-bibtex.
Avoid showing the browser built-in tooltip for links that have the extension enabled.

Finally, version 3 of the Embed API paves the way for supporting non-Sphinx projects in the future.

Embedding content with sphinx-hoverxref

To use sphinx-hoverxref in your Read the Docs project, declare it as part of your dependencies:

requirements.txt

sphinx==4.3.1
sphinx_rtd_theme==1.0.0
sphinx-hoverxref==1.0.0

And add it to your list of Sphinx extensions:

conf.py

extensions = [
    # ...other extensions
    "hoverxref.extension",
]

To enable the extension on all :ref: of your documentation, set the hoverxref_auto_ref to True:

conf.py

hoverxref_auto_ref = True

And you will start seeing tooltips on your internal references. Apart from :ref: roles, you can also enable tooltips on:

Note

sphinx-hoverxref includes the JavaScript embed client in the HTML assets, but it is not yet available as a standalone library that can be reused with standard frontend packaging tools. If you would like to see this happening, let us know.

Calling the Embed API directly

As explained in our embedding guide, you can call the API directly from any HTTP client:

$ curl -s "https://readthedocs.org/api/v3/embed/\
> ?url=https://docs.readthedocs.io/en/latest/features.html\
> %23read-the-docs-features" | python -m json.tool
{
  "url": "https://docs.readthedocs.io/en/latest/features.html#read-the-docs-features",
  "fragment": "read-the-docs-features",
  "content": "<div class=\"section\" id=\"read-the-docs-features\">\n<h1>Read the Docs ...",
  "external": false
}

Or visually explore the query in the web interface instead.

The reference documentation includes more detail about the parameters and return values of the API.

Try it out!

We would like to invite the community to try out these features and send us feedback. With the help of our users, we will keep moving towards a more cohesive documentation ecosystem of interlinked Python projects.

Considering using Read the Docs for your next Sphinx or MkDocs project? Check out our documentation to get started!

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!