From 024ebea3480e0e1d93e6b4e397c24380d70536ea Mon Sep 17 00:00:00 2001 From: Sarah Gibson Date: Fri, 8 Dec 2023 16:04:19 +0000 Subject: [PATCH 1/9] Add some index pages as placeholders for diataxis framework quadrants --- docs/explanation/index.md | 14 ++++++++++++++ docs/reference/index.md | 14 ++++++++++++++ docs/tutorials/index.md | 14 ++++++++++++++ 3 files changed, 42 insertions(+) create mode 100644 docs/explanation/index.md create mode 100644 docs/reference/index.md create mode 100644 docs/tutorials/index.md diff --git a/docs/explanation/index.md b/docs/explanation/index.md new file mode 100644 index 0000000..9bc2e5a --- /dev/null +++ b/docs/explanation/index.md @@ -0,0 +1,14 @@ +(explanation)= +# Explanation + +The documentation in this sections aims to _explain_ and _clarify_ a particular +topic within the project in order to broaden the reader's understanding. + +```{note} +[Read more about the Explanation quadrant of the diataxis framework.](https://diataxis.fr/explanation/) +``` + +```{attention} +This documentation is a Work in Progress! +Please see our [contributing guide](contributing) if you'd like to add to it. +``` diff --git a/docs/reference/index.md b/docs/reference/index.md new file mode 100644 index 0000000..e7f12a3 --- /dev/null +++ b/docs/reference/index.md @@ -0,0 +1,14 @@ +(ref)= +# Reference + +The documentation in this section provides technical descriptions of the +components used throughout the project, and how to use them. + +```{note} +[Read more about the Reference quadrant of the diataxis framework.](https://diataxis.fr/reference/) +``` + +```{attention} +This documentation is a Work in Progress! +Please see our [contributing guide](contributing) if you'd like to add to it. +``` diff --git a/docs/tutorials/index.md b/docs/tutorials/index.md new file mode 100644 index 0000000..c15f976 --- /dev/null +++ b/docs/tutorials/index.md @@ -0,0 +1,14 @@ +(tutorials)= +# Tutorials + +The documentation in this section provides technical descriptions of the +components used throughout the project, and how to use them. + +```{note} +[Read more about the Tutorials quadrant of the diataxis framework.](https://diataxis.fr/tutorials/) +``` + +```{attention} +This documentation is a Work in Progress! +Please see our [contributing guide](contributing) if you'd like to add to it. +``` From 95984bbaff51d89cf26f35e121cf3b71c7043772 Mon Sep 17 00:00:00 2001 From: Sarah Gibson Date: Fri, 8 Dec 2023 16:04:54 +0000 Subject: [PATCH 2/9] Add a reference anchor to the contributing guide --- docs/contributing.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/contributing.md b/docs/contributing.md index 52a4686..94b5915 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -1,3 +1,4 @@ +(contributing)= # Contributing ## Upgrading grafonnet version From e94d3dc328c0274f7ccc628cd673cb0999a3d584 Mon Sep 17 00:00:00 2001 From: Sarah Gibson Date: Fri, 8 Dec 2023 16:36:09 +0000 Subject: [PATCH 3/9] Correct introductory sentence of the tutorials section --- docs/tutorials/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/tutorials/index.md b/docs/tutorials/index.md index c15f976..0e82b73 100644 --- a/docs/tutorials/index.md +++ b/docs/tutorials/index.md @@ -1,8 +1,8 @@ (tutorials)= # Tutorials -The documentation in this section provides technical descriptions of the -components used throughout the project, and how to use them. +The documentation in this section are step-by-step guides that lead the reader +through completing a specific task. ```{note} [Read more about the Tutorials quadrant of the diataxis framework.](https://diataxis.fr/tutorials/) From 5e24d45ebb8c290dc45d5c0d1941216087597b2f Mon Sep 17 00:00:00 2001 From: Sarah Gibson Date: Fri, 8 Dec 2023 17:05:15 +0000 Subject: [PATCH 4/9] Update the homepage to explain how to the documentation is organised --- docs/index.md | 36 ++++++++++++++++++++++++++++++++++-- 1 file changed, 34 insertions(+), 2 deletions(-) diff --git a/docs/index.md b/docs/index.md index 32223e0..f9aeb26 100644 --- a/docs/index.md +++ b/docs/index.md @@ -16,7 +16,24 @@ to help with this. It uses [jsonnet](https://jsonnet.org/) and [grafonnet](https://github.com/grafana/grafonnet-lib) to generate dashboards completely via code. This can then be deployed on any Grafana instance! -## How-to +## How the documentation is organised + +We are currently using the [diátaxis framework](https://diataxis.fr/) to organise +our docs into four main categories: + +- [**Tutorials**](tutorials): Step-by-step guides to complete a specific task +- **How-To guides**: Directions to solve scenarios faced while using the project. Their titles often complete the sentence "How do I...?" +- [**Explanation**](explanation): More in-depth discussion of topics within the project to broaden understanding. +- [**Reference**](ref): Technical descriptions of the components within the project, and how to use them + +### Tutorials + +```{toctree} +:maxdepth: 2 +tutorials/index.md +``` + +### How-to ```{toctree} :maxdepth: 2 @@ -25,10 +42,25 @@ howto/user-diagnostics.md howto/images.md ``` +### Explanation + +```{toctree} +:maxdepth: 2 +explanation/index.md +``` + +### Reference + +```{toctree} +reference/index.md +``` + ## Contributing +Thank you for considering contributing! You can find some details to help you +get started in the sections below. + ```{toctree} :maxdepth: 2 contributing.md ``` - From 034fefcecee5a3d880777f22f243cc4f064bc236 Mon Sep 17 00:00:00 2001 From: Sarah Gibson Date: Wed, 13 Dec 2023 12:52:52 +0000 Subject: [PATCH 5/9] Add an index file to the how-to section --- docs/howto/index.md | 20 ++++++++++++++++++++ docs/index.md | 6 ++---- 2 files changed, 22 insertions(+), 4 deletions(-) create mode 100644 docs/howto/index.md diff --git a/docs/howto/index.md b/docs/howto/index.md new file mode 100644 index 0000000..c0d2a35 --- /dev/null +++ b/docs/howto/index.md @@ -0,0 +1,20 @@ +(howto)= +# How-To Guides + +The documentation in this section is _goal-oriented_ and designed to guide the +reader through specific steps to reach that goal. + +```{note} +[Read more about the How-To quadrant of the diataxis framework.](https://diataxis.fr/how-to-guides/) +``` + +```{attention} +This documentation is a Work in Progress! +Please see our [contributing guide](contributing) if you'd like to add to it. +``` + +```{toctree} +deploy.md +images.md +user-diagnostics.md +``` diff --git a/docs/index.md b/docs/index.md index f9aeb26..f5e8b3d 100644 --- a/docs/index.md +++ b/docs/index.md @@ -33,13 +33,11 @@ our docs into four main categories: tutorials/index.md ``` -### How-to +### How-to Guides ```{toctree} :maxdepth: 2 -howto/deploy.md -howto/user-diagnostics.md -howto/images.md +howto/index.md ``` ### Explanation From b69dd767c46aa63bfd15bc21685b1fef9191951b Mon Sep 17 00:00:00 2001 From: Sarah Gibson Date: Wed, 13 Dec 2023 12:54:48 +0000 Subject: [PATCH 6/9] Ensure the index page of each section has a toctree --- docs/explanation/index.md | 6 ++++++ docs/reference/index.md | 6 ++++++ docs/tutorials/index.md | 6 ++++++ 3 files changed, 18 insertions(+) diff --git a/docs/explanation/index.md b/docs/explanation/index.md index 9bc2e5a..b7e90e3 100644 --- a/docs/explanation/index.md +++ b/docs/explanation/index.md @@ -12,3 +12,9 @@ topic within the project in order to broaden the reader's understanding. This documentation is a Work in Progress! Please see our [contributing guide](contributing) if you'd like to add to it. ``` + +% As files are added into this folder, you can add them to the below section so +% that they appear in the table of contents +```{toctree} +:maxdepth: 2 +``` diff --git a/docs/reference/index.md b/docs/reference/index.md index e7f12a3..e0599d6 100644 --- a/docs/reference/index.md +++ b/docs/reference/index.md @@ -12,3 +12,9 @@ components used throughout the project, and how to use them. This documentation is a Work in Progress! Please see our [contributing guide](contributing) if you'd like to add to it. ``` + +% As files are added into this folder, you can add them to the below section so +% that they appear in the table of contents +```{toctree} +:maxdepth: 2 +``` diff --git a/docs/tutorials/index.md b/docs/tutorials/index.md index 0e82b73..e9e1bdb 100644 --- a/docs/tutorials/index.md +++ b/docs/tutorials/index.md @@ -12,3 +12,9 @@ through completing a specific task. This documentation is a Work in Progress! Please see our [contributing guide](contributing) if you'd like to add to it. ``` + +% As files are added into this folder, you can add them to the below section so +% that they appear in the table of contents +```{toctree} +:maxdepth: 2 +``` From 30c99d04e917e2beb674e1e1f5fe1d0da4fc7b7f Mon Sep 17 00:00:00 2001 From: Sarah Gibson Date: Wed, 13 Dec 2023 13:07:06 +0000 Subject: [PATCH 7/9] Move deployment instructions to tutorials section --- docs/howto/index.md | 1 - docs/{howto => tutorials}/deploy.md | 0 docs/tutorials/index.md | 3 +-- 3 files changed, 1 insertion(+), 3 deletions(-) rename docs/{howto => tutorials}/deploy.md (100%) diff --git a/docs/howto/index.md b/docs/howto/index.md index c0d2a35..2b408c3 100644 --- a/docs/howto/index.md +++ b/docs/howto/index.md @@ -14,7 +14,6 @@ Please see our [contributing guide](contributing) if you'd like to add to it. ``` ```{toctree} -deploy.md images.md user-diagnostics.md ``` diff --git a/docs/howto/deploy.md b/docs/tutorials/deploy.md similarity index 100% rename from docs/howto/deploy.md rename to docs/tutorials/deploy.md diff --git a/docs/tutorials/index.md b/docs/tutorials/index.md index e9e1bdb..f6f774f 100644 --- a/docs/tutorials/index.md +++ b/docs/tutorials/index.md @@ -13,8 +13,7 @@ This documentation is a Work in Progress! Please see our [contributing guide](contributing) if you'd like to add to it. ``` -% As files are added into this folder, you can add them to the below section so -% that they appear in the table of contents ```{toctree} :maxdepth: 2 +deploy.md ``` From c9f527826b0e7c7e79f4219f5cb7ac82453765b3 Mon Sep 17 00:00:00 2001 From: Sarah Gibson Date: Wed, 13 Dec 2023 13:07:26 +0000 Subject: [PATCH 8/9] Clean-up whitespace in deploy.md and add a reference anchor --- docs/tutorials/deploy.md | 20 ++++++++------------ 1 file changed, 8 insertions(+), 12 deletions(-) diff --git a/docs/tutorials/deploy.md b/docs/tutorials/deploy.md index 285606b..6d749ac 100644 --- a/docs/tutorials/deploy.md +++ b/docs/tutorials/deploy.md @@ -1,5 +1,6 @@ -# How to deploy the dashboards - +(tutorials:deploy)= +# Deploying the dashboards + ```{warning} ANY CHANGES YOU MAKE VIA THE GRAFANA UI WILL BE OVERWRITTEN NEXT TIME YOU RUN deploy.bash. TO MAKE CHANGES, EDIT THE JSONNET FILE AND DEPLOY AGAIN @@ -20,16 +21,15 @@ TO MAKE CHANGES, EDIT THE JSONNET FILE AND DEPLOY AGAIN [node-exporter](https://github.com/prometheus/node_exporter) and [cadvisor](https://github.com/google/cadvisor) enabled. In addition, you should scrape metrics from the hub instance as well. - - + ```{tip} If you're using a prometheus chart older than version `14.*`, then you can deploy the dashboards available prior to the upgrade, in the [`1.0 tag`](https://github.com/jupyterhub/grafana-dashboards/releases/tag/1.0). ``` - -3. `kube-state-metrics` must be configured to add some labels to metrics + +3. `kube-state-metrics` must be configured to add some labels to metrics [since version 2.0](https://kubernetes.io/blog/2021/04/13/kube-state-metrics-v-2-0/). If deployed with the prometheus helm chart, the config should look like this: - + ```yaml kube-state-metrics: metricLabelsAllowlist: @@ -38,7 +38,7 @@ TO MAKE CHANGES, EDIT THE JSONNET FILE AND DEPLOY AGAIN # allowing all labels is probably fine for nodes, since they don't churn much, unlike pods - nodes=[*] ``` - + ```{tip} Make sure this is indented correctly where it should be! ``` @@ -50,7 +50,6 @@ TO MAKE CHANGES, EDIT THE JSONNET FILE AND DEPLOY AGAIN selecting 'API Keys'. The admin permission is needed to query list of data sources so we can auto-populate template variable options (such as list of hubs). - ## Additional prometheus exporters Some very useful metrics (such as home directory free space) require @@ -134,7 +133,6 @@ spec: You will likely only need to adjust the `claimName` above to use this example. - (howto:deploy:per-user-home-dir)= ### Per-user home directory metrics (size, last modified, total entries, etc) @@ -223,7 +221,6 @@ spec: You will likely only need to adjust the `claimName` above to use this example. - ## Deploy the dashbaords There's a helper `deploy.py` script that can deploy the dashboards to any grafana installation. @@ -250,4 +247,3 @@ If your Grafana instance uses a self-signed certificate, use the `--no-tls-verif ```bash ./deploy.py --no-tls-verify ``` - From 4a32a269ef720031e957fb8bcba6456a2a295d66 Mon Sep 17 00:00:00 2001 From: Sarah Gibson <44771837+sgibson91@users.noreply.github.com> Date: Wed, 10 Jan 2024 17:09:40 +0000 Subject: [PATCH 9/9] Add missing myst reference Co-authored-by: Georgiana --- docs/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/index.md b/docs/index.md index f5e8b3d..8510152 100644 --- a/docs/index.md +++ b/docs/index.md @@ -22,7 +22,7 @@ We are currently using the [diátaxis framework](https://diataxis.fr/) to organi our docs into four main categories: - [**Tutorials**](tutorials): Step-by-step guides to complete a specific task -- **How-To guides**: Directions to solve scenarios faced while using the project. Their titles often complete the sentence "How do I...?" +- [**How-To guides**](howto): Directions to solve scenarios faced while using the project. Their titles often complete the sentence "How do I...?" - [**Explanation**](explanation): More in-depth discussion of topics within the project to broaden understanding. - [**Reference**](ref): Technical descriptions of the components within the project, and how to use them