From e908ea34e229f18d37c0c4428adef0f4fd8473b9 Mon Sep 17 00:00:00 2001 From: Muhan Date: Mon, 6 Jul 2026 14:52:01 +0800 Subject: [PATCH 1/6] Update the Publish on RTD page for DOCPR-2598 --- docs/how-to/publish-on-rtd.rst | 157 +++++++++++++++------------------ 1 file changed, 73 insertions(+), 84 deletions(-) diff --git a/docs/how-to/publish-on-rtd.rst b/docs/how-to/publish-on-rtd.rst index 27507ce..ff34abd 100644 --- a/docs/how-to/publish-on-rtd.rst +++ b/docs/how-to/publish-on-rtd.rst @@ -6,87 +6,76 @@ Publish on Read the Docs ======================== -Publishing your documentation on Read the Docs makes it available to a wider audience -with automatic builds triggered by repository updates. This guide walks you through the -process of setting up your Sphinx Stack project on Read the Docs. - -For Canonical-specific information on how to set up your documentation on Read the Docs, -see the `Read the Docs at Canonical -`_ and `How to -publish documentation on Read the Docs -`_ guides. - -In general, after enabling the Sphinx Stack for your documentation, follow these steps -to build and publish your documentation on Read the Docs: - -1. Make sure your documentation :ref:`builds without errors or warnings `. -#. Log into Read the Docs. -#. In your account settings, navigate to :guilabel:`Connected services` and check that - your GitHub account is listed. If it's not listed, add a connection to GitHub. See - `How to connect your Read the Docs account to your Git provider - `__. -#. Use the `manual import `__ to - create a project. -#. Specify the path to the ``.readthedocs.yaml`` file for your build. To do this, - navigate to :guilabel:`Admin` > :guilabel:`Settings` and specify the path under "Path - for ``.readthedocs.yaml``". - - For example, if your documentation is stored in the ``docs/`` directory, specify the - path as ``docs/.readthedocs.yaml``. -#. Update the relative paths in the ``.readthedocs.yaml`` file to match the structure of - your project. You might need to update the file paths specified in the following - fields: - - * ``job.post_checkout`` - * ``sphinx.configuration`` - * ``python.install.requirements`` - -After this initial setup, your documentation should build successfully if your project -is hosted from a public repository. If you get any errors, check the build log for -indications on what the problem is. - -If your project was imported from a private repository, your initial build will fail -because Read the Docs won't have access to clone the repository. You need to copy your -project's public key from Read the Docs and add it as a deploy key to the repository, -then re-run the build in Read the Docs. - - -Configure the webhook ---------------------- - -If you have administrator privileges for the GitHub repository that you are adding, the -integration webhook (which is responsible for automatically building the documentation -when the repository changes) is created automatically. - -If you don't have administrator privileges, the webhook must be set up by someone who -does. The person with administrator privileges must have connected their Read the Docs -account to GitHub. See `How to connect your Read the Docs account to your Git provider -`__. - -See `How to manually configure a Git repository integration -`__ if -you want to set up the -webhook manually. - - -Make your documentation public ------------------------------- - -By default, Read the Docs publishes your documentation for logged-in users only. - -To make the documentation public, you must configure the privacy level for each version -of the documentation separately. You can do this by navigating to the -:guilabel:`Versions` tab and changing the :guilabel:`Privacy Level` for each version. - - -Enable PR previews ------------------- - -To make Read the Docs automatically build your documentation when a pull request is -opened or updated on GitHub, enable PR reviews for your project. - -To do so, navigate to :guilabel:`Admin` > :guilabel:`Settings` and select -:guilabel:`Build pull requests for this project`. - -Read the Docs will then automatically build the documentation for each pull request, and -the link to the output will be available as one of the checks in the pull request. +Publishing your documentation on Read the Docs makes it available to a wider audience with automatic builds triggered by repository updates. This guide walks you through the process of setting up your Sphinx Stack project on Read the Docs. + +.. note:: + + This guide is intended for the general public. Canonical staff should instead refer to the internal library for company-specific setup instructions. + +Prepare your project and account +--------------------------------- + +- Ensure your documentation :ref:`builds without errors or warnings `. +- Ensure you have the 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. +- If your documentation is hosted on a supported Git provider (such as GitHub, GitLab, or Bitbucket), create a `Read the Docs account `_ and `connect the account to your Git provider `_. If your documentation is not hosted on a supported Git provider, just create a Read the Docs account. +- Prepare the configuration file `(.readthedocs.yaml) `_ for Read the Docs and save this file to the root directory of your documentation repository. + +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 `_. Follow the on-screen instructions to add your project. 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. + +`Check the first build `_. After it's completed successfully, you can view the live documentation from the project home page. If there are any build errors, fix them: + +- If the configuration file (.readthedocs.yaml) is not in the root directory of your repository and if you used the manual method to add your project, specify the path for the configuration file in the Read the Docs project settings. See `How to use a .readthedocs.yaml file in a sub-folder `_. +- 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, copy the public SSH key that is configured for your Read the Docs project and paste it into your repository configuration. See `Configuring your repository `_. +- If your project is hosted from a public repository, your documentation should build successfully. If you get any errors, check the build log for indications on what the problem is. + +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 +^^^^^^^^^^^^^^^^^^^^^^^ + +Automatic builds are not supported on Launchpad. The implementation of webhooks is not compatible with Read the Docs. You have to run the build manually. The following statements apply to GitHub repositories. + +The Read the Docs integration webhook can automatically build your documentation when your GitHub repository changes. If you have permission to manage webhooks for the GitHub repository and you use the automatic way to add it to Read the Docs, the integration webhook is created automatically. Otherwise, the webhook must be set up by someone who has the appropriate permission. To manually set up the webhook, see `How to configure a Git repository integration manually `_. + +Enable pull request builds +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +To make Read the Docs automatically build and preview your documentation when a pull request is opened or updated, open the project Settings and select **Build pull requests** for this project. + +For more information, see `How to configure pull request builds `_ and `Pull request previews `_. + +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. You can do this by navigating to the Versions tab and changing the `Privacy Level `_ for each version. + +Make tagged versions public +"""""""""""""""""""""""""""" + +To ensure all tagged versions of the documentation are automatically set to public, 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 +================================= ==================== + +Change URL versioning scheme +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The default versioning scheme is `Multiple versions with translations `_. If you don't have translations for your documentation, `change the URL versioning scheme `_ under your project Settings. + +Add support to Git LFS +^^^^^^^^^^^^^^^^^^^^^^^ + +By default, Read the Docs can't access large files stored with Git LFS. If your repository contains large files inside the docs, you need extra configuration in .readthedocs.yaml. See `Support Git LFS `_. \ No newline at end of file From f5ca56f5034a562754b2cc1123510fc55cf1db13 Mon Sep 17 00:00:00 2001 From: Muhan Date: Tue, 7 Jul 2026 09:52:29 +0800 Subject: [PATCH 2/6] Apply suggestions from code review Co-authored-by: Andreia --- docs/how-to/publish-on-rtd.rst | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/docs/how-to/publish-on-rtd.rst b/docs/how-to/publish-on-rtd.rst index ff34abd..e1e969e 100644 --- a/docs/how-to/publish-on-rtd.rst +++ b/docs/how-to/publish-on-rtd.rst @@ -17,17 +17,19 @@ Prepare your project and account - Ensure your documentation :ref:`builds without errors or warnings `. - Ensure you have the 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. -- If your documentation is hosted on a supported Git provider (such as GitHub, GitLab, or Bitbucket), create a `Read the Docs account `_ and `connect the account to your Git provider `_. If your documentation is not hosted on a supported Git provider, just create a Read the Docs account. -- Prepare the configuration file `(.readthedocs.yaml) `_ for Read the Docs and save this file to the root directory of your documentation repository. +- 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 `_. +- Prepare the configuration file (`.readthedocs.yaml `_) for Read the Docs and save this file to the root directory of your documentation repository. 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 `_. Follow the on-screen instructions to add your project. 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. -`Check the first build `_. After it's completed successfully, you can view the live documentation from the project home page. If there are any build errors, fix them: +`Check the first build `_. After it completes successfully, you can view the live documentation from the project home page. -- If the configuration file (.readthedocs.yaml) is not in the root directory of your repository and if you used the manual method to add your project, specify the path for the configuration file in the Read the Docs project settings. See `How to use a .readthedocs.yaml file in a sub-folder `_. +If there are any build errors, fix them: + +- If the `.readthedocs.yaml` file is not in the root directory of your repository and if you used the manual method to add your project, specify the path for the configuration file in the Read the Docs project settings. See `How to use a .readthedocs.yaml file in a sub-folder `_. - 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, copy the public SSH key that is configured for your Read the Docs project and paste it into your repository configuration. See `Configuring your repository `_. - If your project is hosted from a public repository, your documentation should build successfully. If you get any errors, check the build log for indications on what the problem is. @@ -39,7 +41,9 @@ Configurations in this section are all optional. Follow the instructions here to Enable automatic builds ^^^^^^^^^^^^^^^^^^^^^^^ -Automatic builds are not supported on Launchpad. The implementation of webhooks is not compatible with Read the Docs. You have to run the build manually. The following statements apply to GitHub repositories. +Automatic builds are not supported on Launchpad because the implementation of webhooks is not compatible with Read the Docs. Builds must be triggered manually on Read The Docs. + +The following statements apply to GitHub repositories only. The Read the Docs integration webhook can automatically build your documentation when your GitHub repository changes. If you have permission to manage webhooks for the GitHub repository and you use the automatic way to add it to Read the Docs, the integration webhook is created automatically. Otherwise, the webhook must be set up by someone who has the appropriate permission. To manually set up the webhook, see `How to configure a Git repository integration manually `_. @@ -75,7 +79,7 @@ Change URL versioning scheme The default versioning scheme is `Multiple versions with translations `_. If you don't have translations for your documentation, `change the URL versioning scheme `_ under your project Settings. -Add support to Git LFS +Add support for Git LFS ^^^^^^^^^^^^^^^^^^^^^^^ By default, Read the Docs can't access large files stored with Git LFS. If your repository contains large files inside the docs, you need extra configuration in .readthedocs.yaml. See `Support Git LFS `_. \ No newline at end of file From 12eb84f565c07a740393bf51dbe2fb20a49c364a Mon Sep 17 00:00:00 2001 From: Muhan Date: Wed, 8 Jul 2026 11:25:54 +0800 Subject: [PATCH 3/6] Apply suggestions from code review Co-authored-by: JJ Coldiron --- docs/how-to/publish-on-rtd.rst | 21 ++++++++------------- 1 file changed, 8 insertions(+), 13 deletions(-) diff --git a/docs/how-to/publish-on-rtd.rst b/docs/how-to/publish-on-rtd.rst index e1e969e..d5f6e19 100644 --- a/docs/how-to/publish-on-rtd.rst +++ b/docs/how-to/publish-on-rtd.rst @@ -18,7 +18,7 @@ Prepare your project and account - Ensure your documentation :ref:`builds without errors or warnings `. - Ensure you have the 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. - 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 `_. -- Prepare the configuration file (`.readthedocs.yaml `_) for Read the Docs and save this file to the root directory of your documentation repository. +- In the root of your documentation repository, prepare the `.readthedocs.yaml `_ file. Add your project to Read the Docs --------------------------------- @@ -30,7 +30,7 @@ Log in to the Read the Docs dashboard to add a project. If you are the repositor If there are any build errors, fix them: - If the `.readthedocs.yaml` file is not in the root directory of your repository and if you used the manual method to add your project, specify the path for the configuration file in the Read the Docs project settings. See `How to use a .readthedocs.yaml file in a sub-folder `_. -- 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, copy the public SSH key that is configured for your Read the Docs project and paste it into your repository configuration. See `Configuring your repository `_. +- 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 from a public repository, your documentation should build successfully. If you get any errors, check the build log for indications on what the problem is. Additional configuration @@ -41,9 +41,7 @@ Configurations in this section are all optional. Follow the instructions here to Enable automatic builds ^^^^^^^^^^^^^^^^^^^^^^^ -Automatic builds are not supported on Launchpad because the implementation of webhooks is not compatible with Read the Docs. Builds must be triggered manually on Read The Docs. - -The following statements apply to GitHub repositories only. +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. The Read the Docs integration webhook can automatically build your documentation when your GitHub repository changes. If you have permission to manage webhooks for the GitHub repository and you use the automatic way to add it to Read the Docs, the integration webhook is created automatically. Otherwise, the webhook must be set up by someone who has the appropriate permission. To manually set up the webhook, see `How to configure a Git repository integration manually `_. @@ -59,12 +57,9 @@ 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. You can do this by navigating to the Versions tab and changing the `Privacy Level `_ for each version. - -Make tagged versions public -"""""""""""""""""""""""""""" +To make your documentation publicly accessible, you must configure the privacy level for each version of the documentation separately. Navigate to the Versions tab and change the `Privacy Level `_ for each version. -To ensure all tagged versions of the documentation are automatically set to public, add an `Automation Rule `_ under the project Settings with the following configuration: +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 @@ -77,9 +72,9 @@ Action Make version public Change URL versioning scheme ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The default versioning scheme is `Multiple versions with translations `_. If you don't have translations for your documentation, `change the URL versioning scheme `_ under your project Settings. +The default versioning scheme is `Multiple versions with translations `_. If you don't have translations for your documentation, `change the URL versioning scheme `_. -Add support for Git LFS +Add support for Git Large File Storage ^^^^^^^^^^^^^^^^^^^^^^^ -By default, Read the Docs can't access large files stored with Git LFS. If your repository contains large files inside the docs, you need extra configuration in .readthedocs.yaml. See `Support Git LFS `_. \ No newline at end of file +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 `__. \ No newline at end of file From a4b52bde1134f79773ead1cfc2ee95ec9bcec0f3 Mon Sep 17 00:00:00 2001 From: Muhan Date: Wed, 8 Jul 2026 11:53:18 +0800 Subject: [PATCH 4/6] Incorporate JJ's comments --- docs/how-to/publish-on-rtd.rst | 53 +++++++++++++++++++--------------- 1 file changed, 30 insertions(+), 23 deletions(-) diff --git a/docs/how-to/publish-on-rtd.rst b/docs/how-to/publish-on-rtd.rst index d5f6e19..cd94902 100644 --- a/docs/how-to/publish-on-rtd.rst +++ b/docs/how-to/publish-on-rtd.rst @@ -3,78 +3,85 @@ .. _publish-on-rtd: + Publish on Read the Docs ======================== Publishing your documentation on Read the Docs makes it available to a wider audience with automatic builds triggered by repository updates. This guide walks you through the process of setting up your Sphinx Stack project on Read the Docs. -.. note:: - - This guide is intended for the general public. Canonical staff should instead refer to the internal library for company-specific setup instructions. Prepare your project and account --------------------------------- - Ensure your documentation :ref:`builds without errors or warnings `. - Ensure you have the 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. -- 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 `_. -- In the root of your documentation repository, prepare 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 `__. +- In the root of your documentation repository, prepare the `.readthedocs.yaml `__ file. + 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 `_. Follow the on-screen instructions to add your project. 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. +Log in to the `Read the Docs dashboard `__ to add a project. If you are the repository administrator, `add the project automatically `__. Follow the on-screen instructions to add your project. 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. -`Check the first build `_. After it completes successfully, you can view the live documentation from the project home page. +`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 the `.readthedocs.yaml` file is not in the root directory of your repository and if you used the manual method to add your project, specify the path for the configuration file in the Read the Docs project settings. See `How to use a .readthedocs.yaml file in a sub-folder `_. -- 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 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 from a public repository, your documentation should build successfully. If you get any errors, check the build log for indications on what the problem is. + 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 ^^^^^^^^^^^^^^^^^^^^^^^ 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. -The Read the Docs integration webhook can automatically build your documentation when your GitHub repository changes. If you have permission to manage webhooks for the GitHub repository and you use the automatic way to add it to Read the Docs, the integration webhook is created automatically. Otherwise, the webhook must be set up by someone who has the appropriate permission. To manually set up the webhook, see `How to configure a Git repository integration manually `_. +The Read the Docs integration webhook can automatically build your documentation when your GitHub repository changes. If you have permission to manage webhooks for the GitHub repository and added it to Read the Docs automatically, the integration webhook was created automatically. Otherwise, the webhook must be set up by someone with the appropriate permission. To manually set up the webhook, refer to `How to configure a Git repository integration manually `__. + Enable pull request builds ^^^^^^^^^^^^^^^^^^^^^^^^^^ -To make Read the Docs automatically build and preview your documentation when a pull request is opened or updated, open the project Settings and select **Build pull requests** for this project. +To build and preview your documentation whenever a pull request is opened or updated, open the project Settings and select :guilabel:`Build pull requests` for this project. -For more information, see `How to configure pull request builds `_ and `Pull request previews `_. 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 and change the `Privacy Level `_ for each version. +To make your documentation publicly accessible, you must configure the privacy level for each version of the documentation separately. Navigate to the Versions tab and change 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: + +.. list-table:: + :widths: 60 40 + :header-rows: 1 -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 -================================= ==================== -Configuration field Value -================================= ==================== -Version type Tag -Version predefined match pattern Any version -Action Make version public -================================= ==================== Change URL versioning scheme ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The default versioning scheme is `Multiple versions with translations `_. If you don't have translations for your documentation, `change the URL versioning scheme `_. +The default versioning scheme is `Multiple versions with translations `__. If you don't have translations for your documentation, `change the URL versioning scheme `__. + 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 `__. \ No newline at end of file From 060e84d373ca9911cbc3ffabc7c4b9b89634c0ea Mon Sep 17 00:00:00 2001 From: Muhan Date: Tue, 14 Jul 2026 15:55:48 +0800 Subject: [PATCH 5/6] merge the library page into SSD --- docs/how-to/publish-on-rtd.rst | 59 ++++++++++++++++++++++++++++++---- 1 file changed, 52 insertions(+), 7 deletions(-) diff --git a/docs/how-to/publish-on-rtd.rst b/docs/how-to/publish-on-rtd.rst index cd94902..f275279 100644 --- a/docs/how-to/publish-on-rtd.rst +++ b/docs/how-to/publish-on-rtd.rst @@ -15,14 +15,28 @@ Prepare your project and account - Ensure your documentation :ref:`builds without errors or warnings `. - Ensure you have the 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. -- 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 `__. - In the root of your documentation repository, prepare 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 `__. For Canonical staff, the Read the Docs account is automatically created during the onboarding process and connected to our Google SSO: + + 1. Log in to the `Read the Docs dashboard `__ using the :guilabel:`Sign in with Google` option. + 2. Ask on the `~Documentation `__ Mattermost channel to be added to your specific team. + 3. Accept the invitation that is sent to your email. Make sure you are logged in to Read the Docs with your Google account when you do this. 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 `__. Follow the on-screen instructions to add your project. 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. +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:: + + If your repository does not have a main branch and you don't specify the correct default branch, the build will default to main and will not be able to check out the repository and find the correct branch. If this happens, the solution is to add a main branch to the project until you're able to build it once, then specify the correct branch. `Check the first build `__. After it completes successfully, you can view the live documentation from the project home page. @@ -32,8 +46,44 @@ If there are any build errors, fix them: - If your project is hosted from a public repository, your documentation should build successfully. If you get any errors, check the build log for indications on what the problem is. +Canonical-specific configuration +--------------------------------- + +After the initial build, some Canonical-specific configurations are required, as listed below. For information about other advanced configurations, see :ref:`Additional configuration `. + + +Change the host URL to documentation.ubuntu.com +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +By default, your documentation URL is ``https://canonical-.readthedocs-hosted.com``, where ```` is the slug you specified when adding the project. Change the host URL to be ``https://documentation.ubuntu.com``: + +1. Log in to the `Read the Docs dashboard `__. +2. Locate the "Ubuntu documentation library" project and go to :guilabel:`Settings > Subprojects` to add a subproject. +3. Select your project to connect as a subproject from the Subproject dropdown list. +4. (Optional) To use a different name in the URL structure, specify the name in the :guilabel:`Alias` field. Leave it blank to use the name you specified when adding your project. +5. Click :guilabel:`Add subproject`. + +Your documentation URL has changed to ``https://documentation.ubuntu.com/``. + + +Canonical-only documentation +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +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. Please 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 theme 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 ------------------------ +.. _additional-configuration: Configurations in this section are all optional. Follow the instructions here to configure your Read the Docs project according to your preferences. @@ -75,11 +125,6 @@ If your documentation publishes tagged versions that should be public by default - Make version public -Change URL versioning scheme -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The default versioning scheme is `Multiple versions with translations `__. If you don't have translations for your documentation, `change the URL versioning scheme `__. - Add support for Git Large File Storage ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ From f7da4ec43e25ef26f2814dba9da6d633ce387199 Mon Sep 17 00:00:00 2001 From: Muhan Date: Tue, 14 Jul 2026 16:15:52 +0800 Subject: [PATCH 6/6] add "onboarding" --- docs/.custom_wordlist.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/.custom_wordlist.txt b/docs/.custom_wordlist.txt index 529c24a..11aec07 100644 --- a/docs/.custom_wordlist.txt +++ b/docs/.custom_wordlist.txt @@ -24,6 +24,7 @@ LLMs? Multipass npm otf +onboarding plantuml PNG Pygments