|
1 |
| -How to manage subprojects |
2 |
| -========================= |
| 1 | +Managing subprojects |
| 2 | +==================== |
3 | 3 |
|
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. |
6 | 6 |
|
7 | 7 | .. seealso::
|
8 | 8 |
|
9 | 9 | :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. |
11 | 12 |
|
12 | 13 | Adding a subproject
|
13 | 14 | -------------------
|
14 | 15 |
|
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: |
18 | 17 |
|
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` |
23 | 21 |
|
| 22 | +* Choose a project to connect as a subproject using the :guilabel:`Subproject` dropdown |
24 | 23 |
|
25 | 24 | .. note::
|
26 | 25 |
|
27 |
| - |org_brand| |
| 26 | + For users of |org_brand| |
28 | 27 | You need to be *maintainer* of a subproject in order to choose it from your main project.
|
29 | 28 |
|
30 |
| - |com_brand| |
| 29 | + For users of |com_brand| |
31 | 30 | You need to have *admin access* to the subproject in order to choose it from your main project.
|
32 | 31 |
|
| 32 | +.. figure:: /img/screenshots/community-project-subproject-create.png |
| 33 | + :align: center |
| 34 | + :alt: Project subproject creation |
33 | 35 |
|
34 |
| -Editing a subproject |
35 |
| --------------------- |
| 36 | + Project subproject creation |
36 | 37 |
|
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` |
41 | 42 |
|
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. |
43 | 45 |
|
| 46 | +.. figure:: /img/screenshots/community-project-subproject-list.png |
| 47 | + :align: center |
| 48 | + :alt: Project subproject list with a new subproject added |
44 | 49 |
|
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 |
46 | 60 | ---------------------
|
47 | 61 |
|
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. |
50 | 68 |
|
51 |
| -Your subproject will be removed immediately and will be served from it's own domain: |
| 69 | +Deleting a subproject |
| 70 | +--------------------- |
52 | 71 |
|
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. |
55 | 74 |
|
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.** |
0 commit comments