Read the Docs supports multiple versions of your repository.
On initial import,
we will create a
This will point at the default branch for your VCS control:
We also create a
if your project has any tagged releases.
stable will be automatically kept up to date to point at your highest version.
If you want a custom
create either a tag or branch in your project with that name.
When you have Incoming Webhooks and Automation configured for your repository, we will automatically build each version when you push a commit.
How we envision versions working¶
In the normal case,
latest version will always point to the most up to date development code.
If you develop on a branch that is different than the default for your VCS,
you should set the Default Branch to that branch.
You should push a tag for each version of your project.
These tags should be numbered in a way that is consistent with semantic versioning.
This will map to your
stable branch by default.
We in fact are parsing your tag names against the rules given by
PEP 440. This spec allows “normal” version numbers like
well as pre-releases. An alpha version or a release candidate are examples
of pre-releases and they look like this:
We only consider non pre-releases for the
stable version of your
If you have documentation changes on a long-lived branch, you can build those too. This will allow you to see how the new docs will be built in this branch of the code. Generally you won’t have more than 1 active branch over a long period of time. The main exception here would be release branches, which are branches that are maintained over time for a specific release number.
States define the visibility of a version across the site. You can change the states of a version from the Versions tab of your project.
Docs for this version are visible
Builds can be triggered for this version
Docs for this version aren’t visible
Builds can’t be triggered for this version
When you deactivate a version, its docs are removed.
Privacy levels are only supported on Read the Docs for Business.
It means that everything is available to be seen by everyone.
Private versions are available only to people who have permissions to see them. They will not display on any list view, and will 404 when you link them to others. If you want to share your docs temporarily, see Sharing.
In addition, if you want other users to view the build page of your public versions, you’ll neeed to the set the privacy level of your project to public.
This is a banner that appears on the top of every page of your docs that aren’t stable or latest. This banner has a text with a link redirecting the users to the latest version of your docs.
This feature is disabled by default on new projects, you can enable it in the admin section of your docs (Admin > Advanced Settings).
The banner will be injected in an HTML element with the
main role or in the
<div role="main"> <!-- The banner would be injected here --> ... </div>
<main> <!-- The banner would be injected here --> ... </main>
Redirects on root URLs¶
When a user hits the root URL for your documentation,
they will be redirected to the Default version.
This defaults to latest,
but could also point to your latest released version.