From 281a876022062c4ae5ca061c2e5e12514d89e36e Mon Sep 17 00:00:00 2001 From: alhendrickson <159636032+alhendrickson@users.noreply.github.com.> Date: Wed, 4 Jun 2025 08:33:30 +0000 Subject: [PATCH 1/3] Add Readthedocs sphinx build action --- .github/workflows/doc-build.yml | 24 +++++++++++++++++++ docs/observability/customization/_index.md | 19 +++++++++++---- .../customization/alerts-customization.md | 2 -- .../customization/blackbox-exporter-config.md | 8 +++---- docs/observability/setup/production-setup.md | 2 +- 5 files changed, 43 insertions(+), 12 deletions(-) create mode 100644 .github/workflows/doc-build.yml diff --git a/.github/workflows/doc-build.yml b/.github/workflows/doc-build.yml new file mode 100644 index 0000000..70b7227 --- /dev/null +++ b/.github/workflows/doc-build.yml @@ -0,0 +1,24 @@ +name: documentation-build + +on: + push: + branches: + - '**' + tags: + - 'v*.*.*' + release: + types: [published] +jobs: + build: + runs-on: ubuntu-latest + env: + working-directory: ./docs + steps: + - uses: actions/checkout@v3 + - name: Build docs + run: | + cd docs + pip3 install -r requirements.txt + make clean + # Fail buiild on any docs warning + make html O=-W \ No newline at end of file diff --git a/docs/observability/customization/_index.md b/docs/observability/customization/_index.md index 715e31b..f0de41b 100644 --- a/docs/observability/customization/_index.md +++ b/docs/observability/customization/_index.md @@ -1,11 +1,20 @@ # Customization +## Grafana Customization ```{include} custom-dashboards.md -:heading-offset: 1 +:heading-offset: 2 ``` +```{include} alerts-customization.md +:heading-offset: 2 +``` + +## Prometheus Customization ```{include} custom-prometheus-configs.md -:heading-offset: 1 +:heading-offset: 2 +``` +```{include} blackbox-exporter-config.md +:heading-offset: 2 ``` @@ -13,7 +22,9 @@ :titlesonly: :hidden: -custom-prometheus-configs.md -custom-dashboards.md +custom-prometheus-configs +custom-dashboards +alerts-customization +blackbox-exporter-config ``` \ No newline at end of file diff --git a/docs/observability/customization/alerts-customization.md b/docs/observability/customization/alerts-customization.md index 4915913..7314947 100644 --- a/docs/observability/customization/alerts-customization.md +++ b/docs/observability/customization/alerts-customization.md @@ -40,5 +40,3 @@ To define additional alert rules, create files in: Grafana will automatically load these at startup. ---- - diff --git a/docs/observability/customization/blackbox-exporter-config.md b/docs/observability/customization/blackbox-exporter-config.md index f4e542d..dbc1a24 100644 --- a/docs/observability/customization/blackbox-exporter-config.md +++ b/docs/observability/customization/blackbox-exporter-config.md @@ -4,7 +4,7 @@ To define how a probe behaves (e.g., add basic auth, headers, timeout, method), we will configure a module in the Blackbox Exporter config. -#### Create a Blackbox Exporter Config file +### 1. Create a Blackbox Exporter Config file You will need to create a new file, and then mount it over the existing provided vconfig @@ -51,7 +51,7 @@ This example adds a module named `http_2xx_custom` that adds some basic auth cre --- -#### Reference the new module in your prober config +### 2. Reference the new module in your prober config In your probe YAML file, reference the module in the `module` field of the `labels` section: @@ -63,7 +63,7 @@ In your probe YAML file, reference the module in the `module` field of the `labe module: http_2xx_custom # Optional - overrides the default Blackbox module ``` -#### Mount the config file +### 3. Mount the config file You lastly need to mount the new config file and refer to it in docker compose ``` @@ -77,5 +77,3 @@ You lastly need to mount the new config file and refer to it in docker compose command: - "--config.file=/config/custom-blackbox-config.yml" ``` - ---- \ No newline at end of file diff --git a/docs/observability/setup/production-setup.md b/docs/observability/setup/production-setup.md index 250ea7f..6448f3f 100644 --- a/docs/observability/setup/production-setup.md +++ b/docs/observability/setup/production-setup.md @@ -1,7 +1,7 @@ # Production Setup Tutorial This tutorial guides you through setting up the **CogStack Observability Stack** for production use. -If you're new, we recommend completing the [Quickstart Tutorial](../quickstart.md) first to get a simplified setup running. +If you're new, we recommend completing the [Quickstart Tutorial](../get-started/quickstart.md) first to get a simplified setup running. By the end of the tutorial, you will have a complete stack offering all the observability features, customized to your usage. From 5cfef42f6dff71cbfd95d0065f7f5d36befa4308 Mon Sep 17 00:00:00 2001 From: alhendrickson <159636032+alhendrickson@users.noreply.github.com.> Date: Wed, 4 Jun 2025 09:43:41 +0000 Subject: [PATCH 2/3] Fail on warnings --- .readthedocs.yml | 1 + docs/observability/get-started/quickstart.md | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/.readthedocs.yml b/.readthedocs.yml index 731b37f..2af7806 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -11,6 +11,7 @@ build: sphinx: configuration: docs/conf.py + fail_on_warning: true python: install: diff --git a/docs/observability/get-started/quickstart.md b/docs/observability/get-started/quickstart.md index 28e18a7..35c0e8c 100644 --- a/docs/observability/get-started/quickstart.md +++ b/docs/observability/get-started/quickstart.md @@ -22,7 +22,7 @@ Now go to "http://localhost/grafana" to see the dashboards Thats everything. The stack is running and you can see the availability. -If you can't use the script, see the [Manual Quickstart](../advanced-usage/quickstart-manual.md) to setup your own files. +If you can't use the script, see the [Manual Quickstart](../reference/quickstart-manual.md) to setup your own files. ### Optional Step: Probe your own web page From 9a08e39386cc135d4a9436ec6bdff5742eef8826 Mon Sep 17 00:00:00 2001 From: alhendrickson <159636032+alhendrickson@users.noreply.github.com.> Date: Wed, 4 Jun 2025 11:07:22 +0000 Subject: [PATCH 3/3] Add comment on action --- .github/workflows/doc-build.yml | 4 +++- README.md | 1 + 2 files changed, 4 insertions(+), 1 deletion(-) diff --git a/.github/workflows/doc-build.yml b/.github/workflows/doc-build.yml index 70b7227..25f6c83 100644 --- a/.github/workflows/doc-build.yml +++ b/.github/workflows/doc-build.yml @@ -1,3 +1,5 @@ +# This is a simple action to check that the documentation is building. +# Note the real documentation build is done by readthedocs externally, and none of the files created in this action are used. name: documentation-build on: @@ -15,7 +17,7 @@ jobs: working-directory: ./docs steps: - uses: actions/checkout@v3 - - name: Build docs + - name: Check documentation build run: | cd docs pip3 install -r requirements.txt diff --git a/README.md b/README.md index 9298170..207f428 100644 --- a/README.md +++ b/README.md @@ -2,3 +2,4 @@ This repository contains tools and services used to support CogStack deployments +See the latest documentation on [Readthedocs](https://cogstack-platform-toolkit.readthedocs.io/en/latest/observability/_index.html)