Merge pull request #5278 from sgibson91/howto-docs-refactor

Group howto guides by topic to shorten toctree
2i2c-org · Dec 12, 2024 · 3ebbf48 · 3ebbf48
2 parents 52c5d3e + 6803b53
commit 3ebbf48
Show file tree

Hide file tree

Showing 17 changed files with 40 additions and 14 deletions.
diff --git a/docs/howto/bill.md → docs/howto/budgeting-billing/bill.md b/docs/howto/bill.md → docs/howto/budgeting-billing/bill.md
@@ -64,7 +64,7 @@ AWS management account. If a future cluster deviates from this, you can tell by
 1. On the right sidebar under "Time -> Granularity", ensure its selected as "Monthly"
 1. On the right sidebar under "Group by -> Dimension", select "Linked account"
 1. Click the 'Download as CSV' button
-   ```{figure} ../images/aws-billing-ui.jpg
+   ```{figure} /images/aws-billing-ui.jpg
    AWS billing UI
    ```
 1. Run the following deployer command to convert the generated CSV file into the format required for the invoicing process.
@@ -95,7 +95,7 @@ Currently this is the recommended way of retrieving the costs from GCP.
    It is important to not change the name of the file downloaded from GCP as it is used by the deployer to incur the month we are billing for.
    ```
 
-   ```{figure} ../images/gcp-billing-ui.png
+   ```{figure} /images/gcp-billing-ui.png
    GCP billing UI
    ```
 

diff --git a/docs/howto/budget-alerts.md → .../howto/budgeting-billing/budget-alerts.md b/docs/howto/budget-alerts.md → .../howto/budgeting-billing/budget-alerts.md
diff --git a/docs/howto/cost-attribution/aws.md → ...budgeting-billing/cost-attribution/aws.md b/docs/howto/cost-attribution/aws.md → ...budgeting-billing/cost-attribution/aws.md
diff --git a/docs/howto/cost-attribution/index.md → ...dgeting-billing/cost-attribution/index.md b/docs/howto/cost-attribution/index.md → ...dgeting-billing/cost-attribution/index.md
diff --git a/docs/howto/budgeting-billing/index.md b/docs/howto/budgeting-billing/index.md
@@ -0,0 +1,11 @@
+(budgeting-billing)=
+# Manage Budgets and Billing
+
+This documentation covers tasks relating to budgeting and billing of 2i2c hubs.
+
+```{toctree}
+:maxdepth: 2
+bill
+budget-alerts
+cost-attribution/index
+```
diff --git a/docs/howto/features/index.md b/docs/howto/features/index.md
@@ -29,4 +29,4 @@ rocker.md
 shared-db.md
 static-sites.md
 storage-quota.md
-```
+```
diff --git a/docs/howto/decrease-size-gcp-filestore.md → ...management/decrease-size-gcp-filestore.md b/docs/howto/decrease-size-gcp-filestore.md → ...management/decrease-size-gcp-filestore.md
diff --git a/...owto/filesystem-backups/enable-backups.md → ...ment/filesystem-backups/enable-backups.md b/...owto/filesystem-backups/enable-backups.md → ...ment/filesystem-backups/enable-backups.md
diff --git a/docs/howto/filesystem-backups/index.md → ...em-management/filesystem-backups/index.md b/docs/howto/filesystem-backups/index.md → ...em-management/filesystem-backups/index.md
diff --git a/.../filesystem-backups/restore-filesystem.md → .../filesystem-backups/restore-filesystem.md b/.../filesystem-backups/restore-filesystem.md → .../filesystem-backups/restore-filesystem.md
diff --git a/docs/howto/filesystem-management/index.md b/docs/howto/filesystem-management/index.md
@@ -0,0 +1,10 @@
+(filesystem-management)=
+# Manage Filesystems
+
+This documentation covers tasks related to managing filesystems.
+
+```{toctree}
+:maxdepth: 2
+filesystem-backups/index
+decrease-size-gcp-filestore
+```
diff --git a/docs/howto/custom-jupyterhub-image.md → ...age-management/custom-jupyterhub-image.md b/docs/howto/custom-jupyterhub-image.md → ...age-management/custom-jupyterhub-image.md
diff --git a/docs/howto/image-management/index.md b/docs/howto/image-management/index.md
@@ -0,0 +1,9 @@
+(image-management)=
+# Manage Images
+
+This documentation covers tasks related to image management.
+
+```{toctree}
+custom-jupyterhub-image
+update-env
+```
diff --git a/docs/howto/update-env.md → docs/howto/image-management/update-env.md b/docs/howto/update-env.md → docs/howto/image-management/update-env.md
diff --git a/docs/howto/regenerate-smce-creds.md b/docs/howto/regenerate-smce-creds.md
@@ -1,4 +1,4 @@
-# Regenerating credentials for NASA SMCE accounts
+# Regenerate credentials for NASA SMCE accounts
 
 This document describes how we regenerate credentials for _users_ and the `deployer` when they expire in NASA SMCE accounts.
 

diff --git a/docs/howto/troubleshoot/index.md b/docs/howto/troubleshoot/index.md
@@ -1,4 +1,4 @@
-# Troubleshooting
+# Troubleshoot
 
 We have many different tools at our disposal to troubleshoot
 issues that may arise.

diff --git a/docs/index.md b/docs/index.md
@@ -65,19 +65,15 @@ deployed occasionally as a specific addition.
 :maxdepth: 1
 :caption: How-to guides
 howto/features/index.md
-howto/bill.md
-howto/custom-jupyterhub-image.md
+howto/upgrade-cluster/index.md
+howto/budgeting-billing/index
+howto/image-management/index
+howto/filesystem-management/index
 howto/prepare-for-events/index.md
 howto/manage-domains/index.md
 howto/grafana-github-auth.md
-howto/update-env.md
-howto/upgrade-cluster/index.md
-howto/troubleshoot/index.md
 howto/regenerate-smce-creds.md
-howto/budget-alerts
-howto/decrease-size-gcp-filestore
-howto/filesystem-backups/index
-howto/cost-attribution/index
+howto/troubleshoot/index.md
 ```
 
 ## Topic guides