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

docs/user/guides/administrators.rst

@@ -22,4 +22,5 @@ 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>

docs/user/guides/subprojects.rst

@@ -0,0 +1,43 @@
+How to manage subprojects
+=========================
+
+This guide shows you how to add a subproject to your 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 menu.
+From this page you can add a subproject by typing in the project slug.
+
+Immediately after adding the subproject, its default version will be visible from the link displayed in the list of subprojects.
+
+.. note::
+
+   * On |org_brand|, you need to be maintainer of a subproject in order to choose it from your main project.
+   * On |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:`|:memo:|` in the list of subprojects.
+On the following page, it's possible to both change the alias and source project.
+Click :guilabel:`Update subproject` to save your changes.
+
+What is visible in ``/projects/<subproject-alias>/`` will be updated immediately when you save your changes.
+
+
+Deleting a subproject
+---------------------
+
+You can edit a subproject at any time by clicking :guilabel:`|:memo:|` in the list of subprojects.
+On the edit page, click :guilabel:`Delete subproject`.
+
+Your subproject will be removed immediately and it will stop redirecting from its own domain.
+
+Deleting a subproject does not mean to completely remove that project.
+It is solely about removing the reference from the main project.

docs/user/index.rst

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

docs/user/subprojects.rst

@@ -1,43 +1,73 @@
-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 projects can be configured to make other *subprojects* available on the website of the *main project*.
+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 example, a parent project, ``example-project`` is set up with a subproject, ``plugin``. The
+documentation for ``example-project`` will be available at:
 
-Adding a subproject
--------------------
+https://example-project.readthedocs.io/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.
+The documentation for ``plugin`` will be available under this same path:
 
-Subproject aliases
-~~~~~~~~~~~~~~~~~~
+https://example-project.readthedocs.io/projects/plugin/en/latest/
 
-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.
+.. seealso::
+
+   :doc:`/guides/subprojects`
 
 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.
+This project will be configured with a custom domain.
+Other projects are then added as subprojects to 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:
+
+* `foo`: https://docs.example.com/en/latest/
+* `bar`: https://docs.example.com/projects/bar/en/latest/
+
+.. note::
+
+   The terms "parent" and "child" are also used,
+   where the main project is the parent and all subprojects are a child.
+   You can **not** have a child of a child,
+   meaning that you cannot add a subproject to a subproject.
+
+Using aliases
+-------------
+
+You can choose an alias for the subproject when it is created.
+This allows you to override the URL that is used to access it,
+giving more control over how you want to structure your projects.
 
-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/
+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.
+
+Typically, a subproject is created with a ``<mainproject>-`` prefix,
+for instance if the main project is called ``foo`` and the subproject is called ``bar``,
+then the subproject's Read the Docs project name will be ``foo-bar``.
+When adding the subproject,
+the alias is set to ``bar`` and the project's URL becomes
+``foo.readthedocs.io/projects/bar``.
+
+When you add a subproject,
+the subproject will not be directly available anymore from its own domain.
+For instance, ``subproject.readthedocs.io/`` will redirect to ``mainproject.readthedocs.io/projects/subproject``.
 
 Custom domain on subprojects
 ----------------------------
@@ -46,6 +76,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
 ------