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 diff --git a/docs/explanation/index.md b/docs/explanation/index.md new file mode 100644 index 0000000..b7e90e3 --- /dev/null +++ b/docs/explanation/index.md @@ -0,0 +1,20 @@ +(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. +``` + +% 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/howto/index.md b/docs/howto/index.md new file mode 100644 index 0000000..2b408c3 --- /dev/null +++ b/docs/howto/index.md @@ -0,0 +1,19 @@ +(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} +images.md +user-diagnostics.md +``` diff --git a/docs/index.md b/docs/index.md index 32223e0..8510152 100644 --- a/docs/index.md +++ b/docs/index.md @@ -16,19 +16,49 @@ 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**](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 + +### Tutorials + +```{toctree} +:maxdepth: 2 +tutorials/index.md +``` + +### How-to Guides ```{toctree} :maxdepth: 2 -howto/deploy.md -howto/user-diagnostics.md -howto/images.md +howto/index.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 ``` - diff --git a/docs/reference/index.md b/docs/reference/index.md new file mode 100644 index 0000000..e0599d6 --- /dev/null +++ b/docs/reference/index.md @@ -0,0 +1,20 @@ +(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. +``` + +% 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/howto/deploy.md b/docs/tutorials/deploy.md similarity index 99% rename from docs/howto/deploy.md rename to docs/tutorials/deploy.md index 285606b..6d749ac 100644 --- a/docs/howto/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 ``` - diff --git a/docs/tutorials/index.md b/docs/tutorials/index.md new file mode 100644 index 0000000..f6f774f --- /dev/null +++ b/docs/tutorials/index.md @@ -0,0 +1,19 @@ +(tutorials)= +# Tutorials + +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/) +``` + +```{attention} +This documentation is a Work in Progress! +Please see our [contributing guide](contributing) if you'd like to add to it. +``` + +```{toctree} +:maxdepth: 2 +deploy.md +```