Add Readthedocs Action (#5)

* Add Readthedocs sphinx build action

* Fail on warnings

* Add comment on action

Author: alhendrickson

.github/workflows/doc-build.yml

@@ -0,0 +1,26 @@
+# 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:
+  push:
+    branches:
+      - '**'
+    tags:
+      - 'v*.*.*'
+  release:
+    types: [published]
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    env:
+      working-directory: ./docs
+    steps:
+      - uses: actions/checkout@v3
+      - name: Check documentation build
+        run: |
+          cd docs
+          pip3 install -r requirements.txt
+          make clean
+          # Fail buiild on any docs warning
+          make html O=-W 

.readthedocs.yml

@@ -11,6 +11,7 @@ build:
 
 sphinx:
   configuration: docs/conf.py
+  fail_on_warning: true
 
 python:
   install:

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)

docs/observability/customization/_index.md

@@ -1,19 +1,30 @@
 # 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
 ```
 
 
 ```{toctree}
 :titlesonly:
 :hidden:
 
-custom-prometheus-configs.md
-custom-dashboards.md
+custom-prometheus-configs
+custom-dashboards
+alerts-customization
+blackbox-exporter-config
 
 ```

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.
 
----
-

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" 
 ```
-
----

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

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.