Merge the library page into SSD for DOCPR-2598

docs/.custom_wordlist.txt

@@ -24,6 +24,7 @@ LLMs?
 Multipass
 npm
 otf
+onboarding
 plantuml
 PNG
 Pygments

docs/how-to/publish-on-rtd.rst

@@ -3,90 +3,130 @@
 
 .. _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.
+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. 
+
+
+Prepare your project and account
+---------------------------------
+
+- Ensure your documentation :ref:`builds without errors or warnings <build-clean>`.
+- 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. 
+- In the root of your documentation repository, prepare the `.readthedocs.yaml <https://docs.readthedocs.com/platform/stable/config-file/index.html>`__ file.
+- Create a `Read the Docs account <https://docs.readthedocs.com/platform/stable/tutorial/index.html#creating-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 <https://docs.readthedocs.com/platform/stable/guides/connecting-git-account.html>`__. 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 <https://readthedocs.com/dashboard/>`__ using the :guilabel:`Sign in with Google` option.
+  2. Ask on the `~Documentation <https://chat.canonical.com/canonical/channels/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 <https://readripman.readthedocs.io/en/latest/glossary.html#term-dashboard>`__ to add a project. If you are the repository administrator, `add the project automatically <https://docs.readthedocs.com/platform/stable/intro/add-project.html#automatically-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 <https://docs.readthedocs.com/platform/stable/intro/add-project.html#manually-add-your-project>`__. 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 <https://docs.readthedocs.com/platform/stable/tutorial/index.html#checking-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 <https://docs.readthedocs.com/platform/stable/guides/creating-project-private-repository.html#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.
+
+
+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 <additional-configuration>`.
+
+
+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 be ``https://documentation.ubuntu.com``:
+
+1. Log in to the `Read the Docs dashboard <https://readthedocs.com/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/<name>``.
+
+
+Canonical-only documentation
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To limit the documentation access to Canonical users, the project needs to be added to the `All Canonical Users <https://app.readthedocs.com/organizations/canonical/teams/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 <https://app.readthedocs.com/organizations/canonical/members/?teams__slug=all-canonical-users&access=owner>`__ or reach out to the `~Documentation <https://chat.canonical.com/canonical/channels/documentation>`__ channel.
+
+
+Change URL versioning scheme
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The default versioning scheme is `Multiple versions with translations <https://docs.readthedocs.com/platform/stable/versioning-schemes.html#multiple-versions-with-translations>`__. Unless your documentation has multiple languages, do not use the theme with translation. `Change the URL versioning scheme <https://docs.readthedocs.com/platform/stable/versioning-schemes.html#how-to-change-the-url-versioning-scheme-of-your-project>`__ under your project Settings to either a single version without translations or multiple versions without translations.
+
+
 
-For Canonical-specific information on how to set up your documentation on Read the Docs,
-see the `Read the Docs at Canonical
-<https://library.canonical.com/documentation/read-the-docs-at-canonical>`_ and `How to
-publish documentation on Read the Docs
-<https://library.canonical.com/documentation/publish-on-read-the-docs>`_ guides.
+Additional configuration
+------------------------
+.. _additional-configuration:
 
-In general, after enabling the Sphinx Stack for your documentation, follow these steps
-to build and publish your documentation on Read the Docs:
+Configurations in this section are all optional. Follow the instructions here to configure your Read the Docs project according to your preferences.
 
-1. Make sure your documentation :ref:`builds without errors or warnings <build-clean>`.
-#. 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
-   <https://docs.readthedocs.com/platform/stable/guides/connecting-git-account.html>`__.
-#. Use the `manual import <https://readthedocs.com/dashboard/import/manual/>`__ 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``
+Enable automatic builds
+^^^^^^^^^^^^^^^^^^^^^^^
 
-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.
+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.
 
-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.
+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 <https://docs.readthedocs.com/platform/stable/guides/setup/git-repo-manual.html#how-to-manually-configure-a-git-repository-integration>`__.
 
 
-Configure the webhook
----------------------
+Enable pull request builds
+^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-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.
+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.
 
-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
-<https://docs.readthedocs.com/platform/stable/guides/connecting-git-account.html>`__.
 
-See `How to manually configure a Git repository integration
-<https://docs.readthedocs.com/platform/stable/guides/setup/git-repo-manual.html>`__ if
-you want to set up the
-webhook manually.
+Make your documentation public (RTD for Business only)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
+By default, Read the Docs publishes your documentation for logged-in users only. 
 
-Make your documentation 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 <https://docs.readthedocs.com/platform/stable/guides/pull-requests.html#privacy-levels>`__ for each version.
 
-By default, Read the Docs publishes your documentation for logged-in users only.
+If your documentation publishes tagged versions that should be public by default, add an `Automation Rule <https://docs.readthedocs.com/platform/stable/guides/automation-rules.html#adding-a-new-automation-rule>`__ under the project Settings with the following configuration:
 
-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.
+.. list-table:: 
+   :widths: 60 40
+   :header-rows: 1
 
+   * - Configuration field
+     - Value
+   * - Version type
+     - Tag
+   * - Version predefined match pattern
+     - Any version
+   * - Action
+     - Make version public
 
-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`.
+Add support for Git Large File Storage
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-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.
+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 <https://docs.readthedocs.com/platform/stable/build-customization.html#support-git-lfs-large-file-storage>`__.