Fix woke errors and overall improvements

.github/workflows/automatic-doc-checks.yml

@@ -13,4 +13,12 @@ jobs:
   documentation-checks:
     uses: canonical/documentation-workflows/.github/workflows/documentation-checks.yaml@main
     with:
-      working-directory: '.'
+      working-directory: '.'
+  build:
+    name: Build
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Build with warnings as errors
+        run: make check-html-build

Makefile

@@ -74,6 +74,9 @@ run: install
 html: install
 	. $(VENV); $(SPHINXBUILD) -b dirhtml "$(SOURCEDIR)" "$(BUILDDIR)" -w $(SPHINXDIR)/warnings.txt $(SPHINXOPTS)
 
+check-html-build: install
+	. $(VENV); $(SPHINXBUILD) -b dirhtml "$(SOURCEDIR)" "$(BUILDDIR)" -E --fail-on-warning --keep-going $(SPHINXOPTS)
+
 epub: install
 	. $(VENV); $(SPHINXBUILD) -b epub "$(SOURCEDIR)" "$(BUILDDIR)" -w $(SPHINXDIR)/warnings.txt $(SPHINXOPTS)
 

contribute.rst

@@ -29,7 +29,5 @@ footer of every page.
 
 For this documentation we use Sphinx and reStructuredText (reST), which is the default plain text markup language used by Sphinx.
 Here are some useful resources on reStructuredText:
-
-.. wokeignore:rule=master
-- `Sphinx reStructuredText Primer <https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`_
+- `Sphinx reStructuredText Primer <https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`_ :none:`wokeignore:rule=master,`
 - `reStructuredText style guide <https://canonical-documentation-with-sphinx-and-readthedocscom.readthedocs-hosted.com/style-guide/>`_ 

custom_conf.py

@@ -171,6 +171,7 @@
 custom_excludes = [
     'doc-cheat-sheet*',
     'README.md',
+    'starter-guide.rst',
     ]
 
 # Add CSS files (located in .sphinx/_static/)

how-to/deploy_candid_k8s.rst

@@ -137,11 +137,9 @@ Appendix
 Don’t have a PostgreSQL database
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. wokeignore:rule=master
-In case you do not have access to a PostgreSQL database you can use Amazon’s RDS to create one. Navigate to the RDS console and select “Create database”. Under “Engine type” select “PostgreSQL”, specify “Master username” and “Master password”. Also make sure to select “Public access” as “Yes”. You can customise all other options to your preference. Once the database is created, navigate to the database’s dashboard. There you will see the “Endpoint” and “Port” strings, which you will need to connect to the database.  Use the following command to configure Candid:
+In case you do not have access to a PostgreSQL database you can use Amazon’s RDS to create one. Navigate to the RDS console and select “Create database”. Under “Engine type” select “PostgreSQL”, specify “Master username” and “Master password”. Also make sure to select “Public access” as “Yes”. You can customise all other options to your preference. Once the database is created, navigate to the database’s dashboard. There you will see the “Endpoint” and “Port” strings, which you will need to connect to the database.  Use the following command to configure Candid: :none:`wokeignore:rule=master,`
 
-.. wokeignore:rule=master
-``juju config candid-k8s dns=’postgres://<master username>:<master password>@<database endpoint>:<database port>/<database name>``
+    ``juju config candid-k8s dns=postgres://<master username>:<master password>@<database endpoint>:<database port>/<database name>`` :none:`wokeignore:rule=master,`
 
 Don’t have certificates
 ~~~~~~~~~~~~~~~~~~~~~~~

how-to/deploy_jimm_k8s.rst

@@ -110,11 +110,9 @@ Appendix
 Don’t have a PostgreSQL database
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. wokeignore:rule=master
-In case you do not have access to a PostgreSQL database you can use Amazon’s RDS to create one. Navigate to the RDS console and select “Create database”. Under “Engine type” select “PostgreSQL”, specify “Master username” and “Master password”. Also make sure to select “Public access” as “Yes”. You can customise all other options to your preference. Once the database is created, navigate to the database’s dashboard. There you will see the “Endpoint” and “Port” strings, which you will need to connect to the database.  Use the following command to configure JIMM:
+In case you do not have access to a PostgreSQL database you can use Amazon’s RDS to create one. Navigate to the RDS console and select “Create database”. Under “Engine type” select “PostgreSQL”, specify “Master username” and “Master password”. Also make sure to select “Public access” as “Yes”. You can customise all other options to your preference. Once the database is created, navigate to the database’s dashboard. There you will see the “Endpoint” and “Port” strings, which you will need to connect to the database.  Use the following command to configure JIMM: :none:`wokeignore:rule=master,`
 
-.. wokeignore:rule=master
-``juju config jimm-k8s dns=’postgres://<master username>:<master password>@<database endpoint>:<database port>/<database name>``
+    ``juju config jimm-k8s dns=postgres://<master username>:<master password>@<database endpoint>:<database port>/<database name>`` :none:`wokeignore:rule=master,`
 
 Don’t have certificates
 ~~~~~~~~~~~~~~~~~~~~~~~