Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Merged
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
26 commits
Select commit Hold shift + click to select a range
fe1834d
Existing text refactored into howto and explanation
benjaoming Dec 7, 2022
98405ef
Improve subproject explanation with some cases of when it's useful
benjaoming Dec 7, 2022
b5a0b28
Apply suggestions from code review by @humitos
benjaoming Dec 13, 2022
dcfd850
Merge branch 'diataxis/main' of github.com:readthedocs/readthedocs.or…
benjaoming Dec 15, 2022
a7f620b
Merge branch 'diataxis/main' of github.com:readthedocs/readthedocs.or…
benjaoming Dec 15, 2022
51f0b65
Really spell out the alias of a subproject vs. its name
benjaoming Dec 15, 2022
06d66bf
Lowercase foo and bar
benjaoming Dec 15, 2022
88539ab
Describe common searching as a main objective of using subprojects, a…
benjaoming Dec 15, 2022
91b6093
Update docs/user/subprojects.rst
benjaoming Dec 16, 2022
7d646ff
Apply suggestions from code review @ericholscher
benjaoming Dec 16, 2022
671268d
Update docs/user/guides/subprojects.rst
benjaoming Dec 16, 2022
6ec729e
Updates to Subprojects Explanation and How-to from @ericholscher feed…
benjaoming Dec 16, 2022
9c558ba
Update introduction, improvents pending...
benjaoming Dec 16, 2022
36d1518
Adds another intro paragraph
benjaoming Dec 16, 2022
be54e81
Also make *main website* emphasized
benjaoming Dec 16, 2022
b2f15c8
Update docs/user/guides/subprojects.rst
benjaoming Dec 16, 2022
0e60438
Update docs/user/guides/subprojects.rst
benjaoming Dec 16, 2022
e2152f6
Apply suggestions from code review @ericholscher
benjaoming Dec 16, 2022
5ccd208
Add mentions of subprojects in Intersphinx how-to and vice versa
benjaoming Dec 20, 2022
56ab513
Thanks PyCharm for the lovely emoji support 📝️📝️📝️
benjaoming Dec 20, 2022
87dc2cd
Make it possible to see from the main example that example-project-pl…
benjaoming Dec 20, 2022
4bff449
Rename all occurrences of foo and bar to example-project and example-…
benjaoming Dec 20, 2022
b08f8ba
Add precision to subproject create/edit form
benjaoming Dec 20, 2022
0abc008
Apply suggestions from code review by @humitos :tada: :+1:
benjaoming Dec 21, 2022
29b9006
Update docs/user/subprojects.rst
benjaoming Dec 22, 2022
f7cbdb7
Merge branch 'diataxis/main' into diataxis/relabel-subprojects
benjaoming Dec 22, 2022
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions docs/user/guides/administrators.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
7 changes: 7 additions & 0 deletions docs/user/guides/intersphinx.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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:

Expand Down
57 changes: 57 additions & 0 deletions docs/user/guides/subprojects.rst
Original file line number Diff line number Diff line change
@@ -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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Re: @humitos comment about HowTo's, screenshots also don't match across .com & .org currently. It will be better once we ship the new templates.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah yeah, maybe with tabbed panels, we can find a clever way to fix this in the future.

It's okay to stick with .org screenshots for now, right? Pretty sure that's the general pattern?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yea, it's fine.

: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.
Binary file added docs/user/img/screenshot_subprojects_list.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
2 changes: 1 addition & 1 deletion docs/user/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -82,6 +82,7 @@ to help you create fantastic documentation for your project.
/custom-domains
/pull-requests
/downloadable-documentation
/subprojects
/single_version
/science

Expand Down Expand Up @@ -232,7 +233,6 @@ out of your documentation and Read the Docs.
:glob:
:caption: Advanced features

subprojects
flyout-menu
feature-flags

Expand Down
91 changes: 65 additions & 26 deletions docs/user/subprojects.rst
Original file line number Diff line number Diff line change
@@ -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:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This sentence is hard to read for me. I'm not sure if "can be made available" is what confuses me, there is a word missing or something else 🙃 --maybe I'm just tired.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's fix it -- being tired is a good benchmark for readability 👍

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yea, can be made available is super passive voice. Is activated or similar would be active voice.


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
humitos marked this conversation as resolved.
Show resolved Hide resolved

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,
benjaoming marked this conversation as resolved.
Show resolved Hide resolved
the subproject will not be directly available anymore from its own domain.
benjaoming marked this conversation as resolved.
Show resolved Hide resolved
For instance, ``example-project-plugin.readthedocs.io/`` will redirect to ``example-project.readthedocs.io/projects/plugin``.
benjaoming marked this conversation as resolved.
Show resolved Hide resolved
benjaoming marked this conversation as resolved.
Show resolved Hide resolved

Custom domain on subprojects
----------------------------
Expand All @@ -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.
benjaoming marked this conversation as resolved.
Show resolved Hide resolved

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
------

Expand Down