Docs: Split Subprojects in Explanation and How-to (Diátaxis) (#9785)

* Existing text refactored into howto and explanation

* Improve subproject explanation with some cases of when it's useful

* Apply suggestions from code review by @humitos

Co-authored-by: Manuel Kaufmann <[email protected]>

* Really spell out the alias of a subproject vs. its name

* Lowercase foo and bar

* Describe common searching as a main objective of using subprojects, add a subsection about Separate release cycles

* Update docs/user/subprojects.rst

Co-authored-by: Eric Holscher <[email protected]>

* Apply suggestions from code review @ericholscher

Co-authored-by: Eric Holscher <[email protected]>

* Update docs/user/guides/subprojects.rst

* Updates to Subprojects Explanation and How-to from @ericholscher feedback

* Update introduction, improvents pending...

* Adds another intro paragraph

* Also make *main website* emphasized

* Update docs/user/guides/subprojects.rst

Co-authored-by: Eric Holscher <[email protected]>

* Update docs/user/guides/subprojects.rst

Co-authored-by: Eric Holscher <[email protected]>

* Apply suggestions from code review @ericholscher

Co-authored-by: Eric Holscher <[email protected]>

* Add mentions of subprojects in Intersphinx how-to and vice versa

* Thanks PyCharm for the lovely emoji support 📝️📝️📝️

* Make it possible to see from the main example that example-project-plugin has a short alias

* Rename all occurrences of foo and bar to example-project and example-project-plugin

* Add precision to subproject create/edit form

* Apply suggestions from code review by @humitos 🎉 👍

Co-authored-by: Manuel Kaufmann <[email protected]>

* Update docs/user/subprojects.rst

Co-authored-by: Manuel Kaufmann <[email protected]>
Co-authored-by: Eric Holscher <[email protected]>

Author: 3 people

docs/user/guides/administrators.rst

@@ -22,6 +22,7 @@ have a look at our :doc:`/tutorial/index`.
    pdf-non-ascii-languages
    importing-private-repositories
    Setup Build Notifications <build-notifications>
+   subprojects
    Configure Pull Request Builds <pull-requests>
    setup-single-sign-on-github-gitlab-bitbucket
    setup-single-sign-on-google-email

docs/user/guides/intersphinx.rst

@@ -14,6 +14,9 @@ While you could just hyperlink directly, there is a better way.
 That is, you could use the ``:ref:`` role to link to sections of other documentation projects.
 Sphinx will ensure that your cross-references to the other project exist and will raise a warning if they are deleted or changed so you can keep your docs up to date.
 
+If you are publishing several Sphinx projects together using Read the Docs' *subprojects* (see :doc:`/subprojects`),
+you should use Intersphinx to reference your subprojects from other projects.
+
 .. note::
 
    You can also use Sphinx's ``linkcheck`` builder to check for broken links.
@@ -48,6 +51,10 @@ And use the ``intersphinx_mapping`` configuration to indicate the name and link
        "sphinx": ("https://www.sphinx-doc.org/en/master/", None),
    }
 
+.. note::
+
+   If you are using Read the Docs' subprojects, you also need to enable the Intersphinx extension on each of the subprojects.
+   For each subproject, you need to add the main project and all the other subprojects to ``intersphinx_mapping``.
 
 Now you can use the ``sphinx`` name with a cross-reference role:
 

docs/user/guides/subprojects.rst

@@ -0,0 +1,57 @@
+How to manage subprojects
+=========================
+
+This guide shows you how to manage subprojects,
+which is a way to host multiple projects under a "main project".
+
+.. seealso::
+
+   :doc:`/subprojects`
+      Read more about what the subproject feature can do and how it works.
+
+Adding a subproject
+-------------------
+
+In the admin dashboard for your project, select :guilabel:`Subprojects` from the left menu.
+From this page you can add a subproject by choosing a project from the :guilabel:`Subproject` dropdown
+and typing an alias in the :guilabel:`Alias` field.
+
+Immediately after adding the subproject, it will be hosted at the URL displayed in the updated list of subprojects.
+
+.. image:: /img/screenshot_subprojects_list.png
+    :alt: Screenshot of a subproject immediately visible in the list after creation
+
+
+.. note::
+
+   |org_brand|
+      You need to be *maintainer* of a subproject in order to choose it from your main project.
+
+   |com_brand|
+      You need to have *admin access* to the subproject in order to choose it from your main project.
+
+
+Editing a subproject
+--------------------
+
+You can edit a subproject at any time by clicking :guilabel:`📝️` in the list of subprojects.
+On the following page, it's possible to both change the subproject and its alias
+using the :guilabel:`Subproject` dropdown and the :guilabel:`Alias` field.
+Click :guilabel:`Update subproject` to save your changes.
+
+The documentations served at ``/projects/<subproject-alias>/`` will be updated immediately when you save your changes.
+
+
+Deleting a subproject
+---------------------
+
+You can delete a subproject at any time by clicking :guilabel:`📝️` in the list of subprojects.
+On the edit page, click :guilabel:`Delete subproject`.
+
+Your subproject will be removed immediately and will be served from it's own domain:
+
+* Previously it was served at: `<main-project-domain>/projects/<subproject-alias>/`
+* Now it will be served at `<subproject-domain>/`
+
+**Deleting a subproject only removes the reference from the main project.**
+It does not completely remove that project.

docs/user/img/screenshot_subprojects_list.png

@@ -82,6 +82,7 @@ to help you create fantastic documentation for your project.
    /custom-domains
    /pull-requests
    /downloadable-documentation
+   /subprojects
    /single_version
    /science
 
@@ -232,7 +233,6 @@ out of your documentation and Read the Docs.
    :glob:
    :caption: Advanced features
 
-   subprojects
    flyout-menu
    feature-flags
 

docs/user/index.rst

@@ -1,43 +1,66 @@
-Subprojects
-===========
+Subprojects: host multiple projects on a single domain
+======================================================
 
-Projects can be configured in a nested manner, by configuring a project as a
-*subproject* of another project. This allows for documentation projects to share
-a search index and a namespace or custom domain, but still be maintained
-independently.
+In this article, you can learn more about how several documentation projects can be combined and presented to the reader on the same website.
 
-For example, a parent project, ``Foo`` is set up with a subproject, ``Bar``. The
-documentation for ``Foo`` will be available at:
+Read the Docs can be configured to make other *projects* available on the website of the *main project* as **subprojects**.
+This allows for documentation projects to share a search index and a namespace or custom domain,
+but still be maintained independently.
 
-https://foo.readthedocs.io/en/latest/
+This is useful for:
 
-The documentation for ``Bar`` will be available under this same path:
+* Organizations that need all their projects visible in one documentation portal or landing page
+* Projects that document and release several packages or extensions
+* Organizations or projects that want to have a common search function for several sets of documentation
 
-https://foo.readthedocs.io/projects/bar/en/latest/
+For a main project ``example-project``, a subproject ``example-project-plugin`` can be made available as follows:
 
-Adding a subproject
--------------------
+* Main project: https://example-project.readthedocs.io/en/latest/
+* Subproject: https://example-project.readthedocs.io/projects/plugin/en/latest/
 
-In the admin dashboard for your project, select "Subprojects" from the menu.
-From this page you can add a subproject by typing in the project slug.
+.. seealso::
 
-Subproject aliases
-~~~~~~~~~~~~~~~~~~
+   :doc:`/guides/subprojects`
+     Learn how to create and manage subprojects
+
+   :doc:`/guides/intersphinx`
+     Learn how to use references between different Sphinx projects, for instance between subprojects
 
-You can use an alias for the subproject when it is created. This allows you to override the URL that is used to access it, giving more configurability to how you want to structure your projects.
 
 Sharing a custom domain
 -----------------------
 
-Projects and subprojects can also be used to share a custom domain with a number
-of projects. To configure this, one project should be established as the parent
-project. This project will be configured with a custom domain. Projects can then
-be added as subprojects to this parent project.
+Projects and subprojects can be used to share a custom domain.
+To configure this, one project should be established as the main project and configured with a custom domain.
+Other projects are then added as subprojects to the main project.
+
+If the example project ``example-project`` was set up with a custom domain,
+``docs.example.com``, the URLs for projects ``example-project`` and ``example-project-plugin`` with alias ``plugin`` would
+respectively be at:
+
+* ``example-project``: https://docs.example.com/en/latest/
+* ``example-project-plugin``: https://docs.example.com/projects/plugin/en/latest/
+
+Using aliases
+-------------
+
+Adding an alias for the subproject allows you to override the URL that is used to access it,
+giving more control over how you want to structure your projects.
+You can choose an alias for the subproject when it is created.
+
+You can set your subproject's project name and :term:`slug` however you want,
+but we suggest prefixing it with the name of the main project.
 
-If the example project ``Foo`` was set up with a custom domain,
-``docs.example.com``, the URLs for projects ``Foo`` and ``Bar`` would
-respectively be at: https://docs.example.com/en/latest/ and
-https://docs.example.com/projects/bar/en/latest/
+Typically, a subproject is created with a ``<mainproject>-`` prefix,
+for instance if the main project is called ``example-project`` and the subproject is called ``plugin``,
+then the subproject's Read the Docs project :term:`slug` will be ``example-project-plugin``.
+When adding the subproject,
+the alias is set to ``plugin`` and the project's URL becomes
+``example-project.readthedocs.io/projects/plugin``.
+
+When you add a subproject,
+the subproject will not be directly available anymore from its own domain.
+For instance, ``example-project-plugin.readthedocs.io/`` will redirect to ``example-project.readthedocs.io/projects/plugin``.
 
 Custom domain on subprojects
 ----------------------------
@@ -46,6 +69,22 @@ Adding a custom domain to a subproject is not allowed,
 since your documentation will always be served from
 the domain of the parent project.
 
+Separate release cycles
+-----------------------
+
+By using subprojects,
+you can present the documentation of several projects
+even though they have separate release cycles.
+
+Your main project may have its own versions and releases,
+while all of its subprojects maintain their own individual versions and releases.
+We recommend that documentation follows the release cycle of whatever it is documenting,
+meaning that your subprojects should be free to follow their own release cycle.
+
+This is solved by having an individual :term:`flyout menu` active for the project that's viewed.
+When the user navigates to a subproject,
+they are presented with a flyout menu matching the subproject's versions and :doc:`/downloadable-documentation`.
+
 Search
 ------