Skip to content

Commit bec61f4

Browse files
authored
Update subproject guide screenshots and directions (#12262)
- refs #12127 <!-- readthedocs-preview docs start --> --- :books: Documentation previews :books: - User's documentation (`docs`): https://docs--12262.org.readthedocs.build/12262/ <!-- readthedocs-preview docs end --> <!-- readthedocs-preview dev start --> - Developer's documentation (`dev`): https://dev--12262.org.readthedocs.build/12262/ <!-- readthedocs-preview dev end -->
1 parent 6a9ee69 commit bec61f4

File tree

8 files changed

+86
-33
lines changed

8 files changed

+86
-33
lines changed

docs/user/guides/setup/index.rst

Lines changed: 3 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -16,9 +16,8 @@ The following how-to guides help you solve common tasks and challenges in the se
1616
⏩️ :doc:`Using custom URL redirects in documentation projects </guides/redirects>`
1717
Configuring your Read the Docs project for redirecting visitors from one location to another.
1818

19-
⏩️ :doc:`Managing subprojects </guides/subprojects>`
20-
Need several projects under the same umbrella?
21-
Start using subprojects, which is a way to host multiple projects under a "main project".
19+
⏩️ :doc:`/guides/subprojects`
20+
Use subprojects to nest multiple projects into a single custom domain or single documentation project.
2221

2322
⏩️ :doc:`Using a .readthedocs.yaml file in a sub-folder </guides/setup/monorepo>`
2423
This guide shows how to configure a Read the Docs project to use a custom path for the ``.readthedocs.yaml`` build configuration.
@@ -44,7 +43,7 @@ The following how-to guides help you solve common tasks and challenges in the se
4443
Connecting your Read the Docs account to your Git provider </guides/connecting-git-account>
4544
Configuring a Git repository manually </guides/setup/git-repo-manual>
4645
Managing custom domains </guides/custom-domains>
47-
Managing subprojects </guides/subprojects>
46+
/guides/subprojects
4847
Hiding a version </guides/hiding-a-version>
4948
Using a .readthedocs.yaml file in a sub-folder </guides/setup/monorepo>
5049
Using custom URL redirects in documentation projects </guides/redirects>

docs/user/guides/subprojects.rst

Lines changed: 49 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -1,57 +1,77 @@
1-
How to manage subprojects
2-
=========================
1+
Managing subprojects
2+
====================
33

4-
This guide shows you how to manage subprojects,
5-
which is a way to host multiple projects under a "main project".
4+
Subprojects can be used to nest projects together under a single parent project,
5+
which is most commonly used to share a single custom domain across multiple projects.
66

77
.. seealso::
88

99
:doc:`/subprojects`
10-
Read more about what the subproject feature can do and how it works.
10+
Learn what the subproject feature can do, how it works,
11+
and how to use custom domains and subproject aliases.
1112

1213
Adding a subproject
1314
-------------------
1415

15-
In the admin dashboard for your project, select :guilabel:`Subprojects` from the left menu.
16-
From this page you can add a subproject by choosing a project from the :guilabel:`Subproject` dropdown
17-
and typing an alias in the :guilabel:`Alias` field.
16+
The following steps can be used to connect two existing projects together:
1817

19-
Immediately after adding the subproject, it will be hosted at the URL displayed in the updated list of subprojects.
20-
21-
.. image:: /img/screenshot_subprojects_list.png
22-
:alt: Screenshot of a subproject immediately visible in the list after creation
18+
* Go to :menuselection:`Settings --> Subprojects` for the project that will act
19+
as your **parent project**.
20+
* Click :guilabel:`Add subproject`
2321

22+
* Choose a project to connect as a subproject using the :guilabel:`Subproject` dropdown
2423

2524
.. note::
2625

27-
|org_brand|
26+
For users of |org_brand|
2827
You need to be *maintainer* of a subproject in order to choose it from your main project.
2928

30-
|com_brand|
29+
For users of |com_brand|
3130
You need to have *admin access* to the subproject in order to choose it from your main project.
3231

32+
.. figure:: /img/screenshots/community-project-subproject-create.png
33+
:align: center
34+
:alt: Project subproject creation
3335

34-
Editing a subproject
35-
--------------------
36+
Project subproject creation
3637

37-
You can edit a subproject at any time by clicking :guilabel:`📝️` in the list of subprojects.
38-
On the following page, it's possible to both change the subproject and its alias
39-
using the :guilabel:`Subproject` dropdown and the :guilabel:`Alias` field.
40-
Click :guilabel:`Update subproject` to save your changes.
38+
* If you would like the subproject to use a different name in the URL structure
39+
of your built documentation, you can alter that subproject :guilabel:`Alias`
40+
field -- otherwise leave this blank.
41+
* Click on :guilabel:`Add subproject`
4142

42-
The documentations served at ``/projects/<subproject-alias>/`` will be updated immediately when you save your changes.
43+
After adding the subproject, the URL the project is served from will by changed to
44+
the URL displayed in the updated list of subprojects.
4345

46+
.. figure:: /img/screenshots/community-project-subproject-list.png
47+
:align: center
48+
:alt: Project subproject list with a new subproject added
4449

45-
Deleting a subproject
50+
Project subproject list with a new subproject added
51+
52+
.. |button-edit| image:: /img/screenshots/community-edit-button.png
53+
:height: 1.5em
54+
:alt: Configure button
55+
.. |button-delete| image:: /img/screenshots/community-delete-button.png
56+
:height: 1.5em
57+
:alt: Delete button
58+
59+
Updating a subproject
4660
---------------------
4761

48-
You can delete a subproject at any time by clicking :guilabel:`📝️` in the list of subprojects.
49-
On the edit page, click :guilabel:`Delete subproject`.
62+
You can update a subproject by clicking the configure button |button-edit| in the list of subprojects.
63+
On the following page, it's possible to change both the subproject and its alias
64+
using the :guilabel:`Subproject` dropdown and the :guilabel:`Alias` field.
65+
Click :guilabel:`Update subproject` to save your changes.
66+
67+
The URL the subproject documentation is served from will be updated after you save your changes.
5068

51-
Your subproject will be removed immediately and will be served from it's own domain:
69+
Deleting a subproject
70+
---------------------
5271

53-
* Previously it was served at: `<main-project-domain>/projects/<subproject-alias>/`
54-
* Now it will be served at `<subproject-domain>/`
72+
You can delete a subproject connection by clicking the delete button |button-delete| in the list of subprojects.
73+
Confirm the deletion on the popup that shows to delete the subproject connection.
5574

56-
**Deleting a subproject only removes the reference from the main project.**
57-
It does not completely remove that project.
75+
The subproject connection will be removed
76+
and the project that was configured as a subproject will return to being served from it's own domain.
77+
**This will not remove either project, only the subproject relationship will be removed.**

docs/user/img/screenshots/business.yml

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -52,3 +52,20 @@
5252
> *
5353
padding: 20
5454
output: business-project-ssh-key.png
55+
56+
# TODO set up this fixture project on community instead
57+
- url: https://app.readthedocs.com/dashboard/read-the-docs-qa-superproject/subprojects/
58+
javascript: |-
59+
document
60+
.querySelectorAll("#edit-content table tr:nth-child(n+2)")
61+
.forEach((el) => { el.remove() });
62+
document
63+
.querySelector("#edit-content table tr td > .ui.tiny.header > .content")
64+
.innerHTML = "<a href='#'>example-subproject</a><a href='#' class='sub header'>https://docs.example.com/projects/example</a>";
65+
selector_all: |-
66+
body
67+
> div.ui.very.padded.container
68+
.column[class*="eleven wide computer"]
69+
> *
70+
padding: 20
71+
output: community-project-subproject-list.png
354 Bytes
Loading
532 Bytes
Loading
12.3 KB
Loading
12.6 KB
Loading

docs/user/img/screenshots/community.yml

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,14 @@
1919
padding: 20
2020
output: community-project-webhook-activity.png
2121

22+
# Just the edit/delete icons
23+
- url: https://app.readthedocs.org/dashboard/test-builds/integrations/
24+
selector: .button:has(> i.fa-wrench.icon)
25+
output: community-edit-button.png
26+
- url: https://app.readthedocs.org/dashboard/test-builds/integrations/
27+
selector: .button:has(> i.fa-trash.icon)
28+
output: community-delete-button.png
29+
2230
- url: https://app.readthedocs.org/dashboard/test-builds/webhooks/616/edit/
2331
javascript: |-
2432
document
@@ -28,3 +36,12 @@
2836
#div_id_secret
2937
padding: 20
3038
output: community-project-webhook-secret.png
39+
40+
- url: https://app.readthedocs.org/dashboard/test-builds/subprojects/create/
41+
selector_all: |-
42+
body
43+
> div.ui.very.padded.container
44+
.ui.grid > .column[class*="eleven wide computer"]
45+
> *
46+
padding: 20
47+
output: community-project-subproject-create.png

0 commit comments

Comments
 (0)