chore: test documentation (#145)

* chore: Test documentation

* docs: fix broken links

.github/workflows/test.yml

@@ -37,10 +37,23 @@ jobs:
     - name: Spec test
       run: |
         docker run --mount type=bind,source=$(pwd)/build/kapow,target=/usr/local/bin/kapow  bbvalabsci/kapow-spec-test-suite:latest behave --tags=~@skip
+  doc-test:
+    runs-on: ubuntu-20.04
+    steps:
+    - uses: actions/checkout@v2
+    - name: Prepare Python env
+      run: |
+        sudo apt-get install -y pipenv
+        cd docs
+        pipenv sync
+    - name: Check for warnings & broken links
+      run: |
+        cd docs
+        SPHINXOPTS="-qW --keep-going" pipenv run make linkcheck html
   release:
     if: github.event_name == 'push' && contains(github.ref, 'refs/tags/')
     runs-on: ubuntu-20.04
-    needs: [ unit-test, spec-test ]
+    needs: [ unit-test, spec-test, doc-test ]
     steps:
     - uses: actions/checkout@v2
       with:

docs/source/concepts/routes.rst

@@ -63,7 +63,7 @@ In the route shown above, a request with a URL ``/register/joe`` would match,
 assigning `joe` to the placeholder ``username``.
 
 *Kapow!* leverages `Gorilla Mux`_ for managing routes.  For the full story, see
-https://github.com/gorilla/mux#examples
+https://github.com/gorilla/mux
 
 
 .. _entrypoint-route-element:

docs/source/conf.py

@@ -51,7 +51,7 @@ templates_path = ['_templates']
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
-exclude_patterns = []
+exclude_patterns = ['latextoc.rst', '**/toc.rst']
 
 rst_prolog = """
 .. role:: tech(code)

docs/source/examples/https_mtls.rst

@@ -46,6 +46,8 @@ Where `path/to/CAfile` is the path to the file containing the CA certificate
 that issued *Kapow!*'s certificate.
 
 
+.. _https_mtls:
+
 Enabling mTLS
 ++++++++++++++
 
@@ -175,7 +177,7 @@ certificate.
 
    In order to enable mutual TLS authentication read the `Nginx documentation`_.
 
-.. _some criteria are met: https://caddyserver.com/v1/docs/automatic-https
+.. _some criteria are met: https://caddyserver.com/docs/automatic-https
 .. _Caddy documentation: https://caddyserver.com/docs/caddyfile/directives/tls
 .. _HAProxy documentation: https://www.haproxy.com/de/documentation/aloha/12-0/traffic-management/lb-layer7/tls/
 .. _Nginx documentation: https://smallstep.com/hello-mtls/doc/server/nginx

docs/source/the_project/quickstart.rst

@@ -117,7 +117,7 @@ Follow the :ref:`installation instructions <installation>`.
 
 
 Write an Init Program :file:`ping-route`
-+++++++++++++++++++++++++++++++++++++++
+++++++++++++++++++++++++++++++++++++++++
 
 *Kapow!* uses init programs/scripts where the endpoints you want
 to expose are defined.

docs/source/tutorial/tutorial01.rst

@@ -82,7 +82,7 @@ Let's Backup that Database!
   OK then, let's it try on your laptop first.
 
   First of all, you have to follow the
-  `installation instructions </the_project/install_and_configure>`_.
+  `installation instructions <installation>`.
 
 **Junior**
 

docs/source/tutorial/tutorial06.rst

@@ -24,7 +24,7 @@ Securing the server
 **Senior**
 
   Yes, I'm pretty sure that those smart guys have thought on that when building
-  Kapow! Have a look at the `documentation </examples/https_mtls>`_.
+  Kapow! Have a look at the `documentation <https_mtls>`.
 
 **Junior**