Versions
Read the Docs supports multiple versions of your repository.
On initial import,
we will create a latest
version.
This will point at the default branch defined in your VCS control
(by default, main
on Git and default
in Mercurial).
If your project has any tags or branches with a name following semantic versioning,
we also create a stable
version, tracking your most recent release.
If you want a custom stable
version,
create either a tag or branch in your project with that name.
When you have Continuous Documentation Deployment configured for your repository, we will automatically build each version when you push a commit.
How we envision versions working
In the normal case,
the 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.
Note
We in fact are parsing your tag names against the rules given by
PEP 440. This spec allows “normal” version numbers like 1.4.2
as
well as pre-releases. An alpha version or a release candidate are examples
of pre-releases and they look like this: 2.0a1
.
We only consider non pre-releases for the stable
version of your
documentation.
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.
Version states
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.
Active
Active
Docs for this version are visible
Builds can be triggered for this version
Inactive
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
Note
Privacy levels are only supported on Business hosting.
Public
It means that everything is available to be seen by everyone.
Private
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 private documentation.
In addition, if you want other users to view the build page of your public versions, you’ll need to the set the privacy level of your project to public.
Logging out
When you log in to a documentation site, you will be logged in until close your browser. To log out, click on the Log out link in your documentation’s flyout menu. This is usually located in the bottom right or bottom left, depending on the theme design. This will log you out from the current domain, but not end any other session that you have active.
Version warning
A banner can be automatically displayed to notify viewers that there may be a more stable version of the documentation available. Specifically:
When the
latest
version is being shown, and there’s also astable
version active and not hidden, then the banner will remind the viewer that some of the documented features may not yet be available, and suggest that the viewer switch to thestable
version.When a version is being shown that is not the
stable
version, and there’s astable
version available, then the banner will suggest that the viewer switch to thestable
version to see the newest documentation.
This feature is enabled by default on projects using the new beta addons.
The beta addons can be enabled by using build.commands
config key or via the new beta dashboard (https://beta.readthedocs.org) going to the admin section of your docs (Admin > Settings)
Note
An older version of this feature is currently only available to projects that have already enabled it. When the updated feature development is finished the toggle setting will be enabled for all projects.
Redirects on root URLs
When a user hits the root URL for your documentation,
for example https://pip.readthedocs.io/
,
they will be redirected to the Default version.
This defaults to latest,
but could also point to your latest released version.