Publish on Read the Docs¶
Canonical documentation, both internal and external, is hosted on Read the Docs. This guide walks you through the process of setting up your Sphinx Stack project on Read the Docs.
Prepare your project and account¶
Ensure your documentation builds without errors or warnings.
Ensure you have permission to manage webhooks for the documentation repository, or get in touch with someone who does. A webhook is needed if you want Read the Docs to automatically build your documentation whenever a change occurs.
In the root of your documentation repository, create the .readthedocs.yaml file.
Create a Read the Docs account. If your documentation is hosted on a supported Git provider (such as GitHub, GitLab, or Bitbucket), connect the account to your Git provider.
Note
Add your project to Read the Docs¶
Log in to the Read the Docs dashboard to add a project. If you are the repository administrator, add the project automatically. If you are not a repository administrator or your documentation is not hosted on a supported Git provider, add the project manually. A build will be triggered after the project is added.
When adding a project, most fields are self-explanatory, and you can leave the default values. Check and update the following fields:
Organization and team: This determines who gets admin access to your Read the Docs project.
Name: This is the slug used in the documentation URL. You cannot change the name after you create the project, so choose carefully!
Default branch: This determines which branch “latest” points to.
Note
Check the first build. After it completes successfully, you can view the live documentation from the project home page.
If there are any build errors, fix them:
If your project is hosted in a private repository, your first build will fail because your repository is not configured to allow Read the Docs to clone the repository. To fix the access issue, follow the steps in Configuring your repository.
If your project is hosted in a public repository, your documentation should build successfully. If you get any errors, check the build log for indications of what the problem is.
Canonical-specific configuration¶
After the initial build, some Canonical-specific configurations are required, as listed below.
Change the host URL to documentation.ubuntu.com¶
By default, your documentation URL is https://canonical-<name>.readthedocs-hosted.com, where <name> is the slug you specified when adding the project. Change the host URL to https://documentation.ubuntu.com:
Log in to the Read the Docs dashboard.
Locate the “Ubuntu documentation library” project and go to Settings > Subprojects to add a subproject.
Select your project to connect as a subproject from the Subproject dropdown list.
(Optional) To use a different name in the URL structure, specify the name in the Alias field. Leave it blank to use the name you specified when adding your project.
Click Add subproject.
Your documentation URL has changed to https://documentation.ubuntu.com/<name>.
Limit documentation access¶
To limit the documentation access to Canonical users, the project needs to be added to the All Canonical Users group. All Canonical users who log in to Read the Docs with Google SSO will be automatically added to this user group and granted read-only permissions to the associated projects.
This operation requires the Owner’s permission to Read the Docs. Contact one of the owners of the Canonical organization or reach out to the ~Documentation channel.
Change URL versioning scheme¶
The default versioning scheme is Multiple versions with translations. Unless your documentation has multiple languages, do not use the scheme with translation. Change the URL versioning scheme under your project Settings to either a single version without translations or multiple versions without translations.
Additional configuration¶
Configurations in this section are all optional. Follow the instructions here to configure your Read the Docs project according to your preferences.
Enable automatic builds¶
The Read the Docs integration webhook can automatically build your documentation when your GitHub repository changes. If you added the GitHub repository to Read the Docs automatically, the integration webhook was already created. Otherwise, the webhook must be set up by someone with the appropriate permission.
To check if the webhook was created, open the project Settings and click Integrations. If the webhook is not listed, someone with the appropriate permissions must manually set it up.
Automatic builds are not supported on Launchpad because its webhooks aren’t compatible with Read the Docs. Builds must be triggered manually on Read The Docs.
Enable pull request builds¶
To build and preview your documentation whenever a pull request is opened or updated, open the project Settings and click Pull request builds to enable it for your project.
Make your documentation public (RTD for Business only)¶
By default, Read the Docs publishes your documentation for logged-in users only.
To make your documentation publicly accessible, you must configure the privacy level for each version of the documentation separately. Navigate to the Versions tab to configure the Privacy Level for each version.
If your documentation publishes tagged versions that should be public by default, add an Automation Rule under the project Settings with the following configuration:
Configuration field |
Value |
|---|---|
Version type |
Tag |
Version predefined match pattern |
Any version |
Action |
Make version public |
Add support for Git Large File Storage¶
By default, Read the Docs can’t access large files stored with Git LFS. If your docs project contains large files, add support for Git LFS.