-
-
Notifications
You must be signed in to change notification settings - Fork 3.6k
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
Changes from all commits
fe1834d
98405ef
b5a0b28
dcfd850
a7f620b
51f0b65
06d66bf
88539ab
91b6093
7d646ff
671268d
6ec729e
9c558ba
36d1518
be54e81
b2f15c8
0e60438
e2152f6
5ccd208
56ab513
87dc2cd
4bff449
b08f8ba
0abc008
29b9006
f7cbdb7
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
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 | ||
: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. |
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: | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe 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. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Let's fix it -- being tired is a good benchmark for readability 👍 There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Yea, |
||
|
||
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 | ||
---------------------------- | ||
|
@@ -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 | ||
------ | ||
|
||
|
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Yea, it's fine.