update doc tooling to Zensical (#223)

* update doc tooling to Zensical

* remove termy

* match pygeoapi theming

Author: tomkralidis

.github/workflows/deploy.docs.yml

@@ -7,22 +7,34 @@ on:
     paths:
       - 'workshop/content/**'
 
-defaults:
-  run:
-    working-directory: workshop/content
-
 jobs:
   build:
     name: Build and Deploy Documentation
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v2
-      - uses: actions/setup-python@v2
+      - uses: actions/checkout@master
+      - uses: actions/setup-python@v5
         with:
           python-version: '3.x'
       - name: Install requirements 📦
         run: |
           python -m pip install --upgrade pip
-          pip install -r requirements.txt
-      - name: Deploy 📦
-        run: mkdocs gh-deploy --config-file mkdocs.yml --strict --force --clean --message 'update website via GitHub Actions'
+          pip install -r workshop/content/requirements.txt
+      - name: Build site 📦
+        run: |
+          zensical build --clean --strict
+          mv site /tmp/
+      - name: checkout gh-pages branch
+        uses: actions/checkout@master
+        with:
+          ref: gh-pages
+      - name: Deploy to GitHub Pages 📦
+        run: |
+          git checkout gh-pages
+          git config --global user.email "tomkralidis@gmail.com"
+          git config --global user.name "Tom Kralidis"
+          ls | grep -v ".nojekyll"| xargs rm -fr
+          mv -f /tmp/site/* .
+          git add .
+          git commit -am "update website via GitHub Actions"
+          git push

.github/workflows/tests.yml

@@ -14,13 +14,13 @@ jobs:
     name: Test documentation build
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v2
-      - uses: actions/setup-python@v2
+      - uses: actions/checkout@master
+      - uses: actions/setup-python@v5
         with:
           python-version: '3.x'
       - name: Install requirements 📦
         run: |
           python -m pip install --upgrade pip
           pip install -r requirements.txt
-      - name: Deploy 📦
-        run: mkdocs build --strict
+      - name: Build 📦
+        run: zensical build --clean --strict

.gitignore

@@ -1,6 +1,7 @@
 .DS_Store
 workshop/exercises/data/tiles
+workshop/content/.cache
 workshop/content/site
 
 .idea
-.venv
+.venv

CONTRIBUTING.md

@@ -92,7 +92,7 @@ Your contribution will be under our [license](https://github.com/geopython/divin
 ### Documentation
 
 * documentation is managed in `workshop/content/docs/` using , in Markdown format
-* [MkDocs](https://www.mkdocs.org) is used to generate the documentation
+* [Zensical](https://zensical.org) is used to generate the documentation
 
 
 ## Suggesting Enhancements

README.md

@@ -22,7 +22,7 @@ the [Workshop environment setup](https://dive.pygeoapi.io/setup).
 
 ### Building the workshop content locally
 
-The workshop manual is powered by [MkDocs](https://www.mkdocs.org) which facilitates easy management
+The workshop manual is powered by [Zensical](https://zensical.org) which facilitates easy management
 of content and publishing. Workshop content is written in Markdown.
 
 
@@ -38,9 +38,9 @@ cd diving-into-pygeoapi/workshop/content
 # install required dependencies
 pip install -r requirements.txt
 # build the website
-mkdocs build
+zensical build
 # serve locally
-mkdocs serve  # website is made available on http://localhost:8000
+zensical serve  # website is made available on http://localhost:8000
 ```
 
 ### Translating the workshop to a different language
@@ -71,10 +71,4 @@ Changes to the GitHub repository result in an automated build and deploy of the
 
 ## Deploying to live site
 
-Website updates are automatically published via GitHub Actions. To publish manually:
-
-```bash
-# NOTE: you require access privileges to the GitHub repository
-# to publish live updates
-mkdocs gh-deploy -m 'add new page on topic x'
-```
+Website updates are automatically published via GitHub Actions.

workshop/content/docs/advanced/cloud.md

@@ -14,19 +14,15 @@ A [Docker image](https://hub.docker.com/r/geopython/pygeoapi) is available for p
 
 === "Linux/Mac"
 
-    <div class="termy">
     ```bash
     docker run -p 5000:80 geopython/pygeoapi:latest
     ```
-    </div>
 
 === "Windows (PowerShell)"
 
-    <div class="termy">
     ```bash
     docker run -p 5000:80 geopython/pygeoapi:latest
     ```
-    </div>
 
 !!! question "Review the pygeoapi Dockerfile"
 
@@ -38,22 +34,17 @@ In a typical configuration one would override the default pygeoapi configuration
 
     === "Linux/Mac"
 
-        <div class="termy">
         ```bash
         docker run -p 5000:80 \ 
         -v $(pwd)/pygeoapi-config.yml:/pygeoapi/local.config.yml \
         -v $(pwd)/geodata:/geodata https://hub.docker.com/r/geopython/pygeoapi:latest
         ```
-        </div>
 
     === "Windows (PowerShell)"
 
-        <div class="termy">
         ```bash
         docker run -p 5000:80 -v ${pwd}/pygeoapi-config.yml:/pygeoapi/local.config.yml -v ${pwd}/geodata:/geodata https://hub.docker.com/r/geopython/pygeoapi:latest
         ```
-        </div>
-
 
 Alternatively, you can build a fresh Docker image including both the configuration and data for the service. 
 
@@ -70,22 +61,18 @@ set the `SCRIPT_NAME` environment variable.
 
 === "Linux/Mac"
 
-    <div class="termy">
     ```bash
     docker run -p 5000:80 -e SCRIPT_NAME='/mypygeoapi' \
     -v $(pwd)/my.config.yml:/pygeoapi/local.config.yml -it geopython/pygeoapi
     # browse to http://localhost:5000/mypygeoapi
     ```
-    </div>
 
 === "Windows (PowerShell)"
 
-    <div class="termy">
     ```bash
     docker run -p 5000:80 -e SCRIPT_NAME='/mypygeoapi' -v ${pwd}/my.config.yml:/pygeoapi/local.config.yml -it geopython/pygeoapi
     # browse to http://localhost:5000/mypygeoapi
     ```
-    </div>
 
 # Summary
 

workshop/content/docs/advanced/cloud.pt.md

@@ -14,19 +14,15 @@ Uma [imagem Docker](https://hub.docker.com/r/geopython/pygeoapi) está disponív
 
 === "Linux/Mac"
 
-    <div class="termy">
     ```bash
     docker run -p 5000:80 geopython/pygeoapi:latest
     ```
-    </div>
 
 === "Windows (PowerShell)"
 
-    <div class="termy">
     ```bash
     docker run -p 5000:80 geopython/pygeoapi:latest
     ```
-    </div>
 
 !!! question "Rever o Dockerfile da pygeoapi"
 
@@ -38,21 +34,17 @@ Numa configuração típica, substituir-se-ia o ficheiro de configuração padr
 
     === "Linux/Mac"
 
-        <div class="termy">
         ```bash
         docker run -p 5000:80 \ 
         -v $(pwd)/pygeoapi-config.yml:/pygeoapi/local.config.yml \
         -v $(pwd)/geodata:/geodata https://hub.docker.com/r/geopython/pygeoapi:latest
         ```
-        </div>
 
     === "Windows (PowerShell)"
 
-        <div class="termy">
         ```bash
         docker run -p 5000:80 -v ${pwd}/pygeoapi-config.yml:/pygeoapi/local.config.yml -v ${pwd}/geodata:/geodata https://hub.docker.com/r/geopython/pygeoapi:latest
         ```
-        </div>
 
 
 Alternativamente, pode construir uma nova imagem Docker incluindo tanto a configuração como os dados para o serviço. 
@@ -70,23 +62,19 @@ definir a variável de ambiente `SCRIPT_NAME`.
 
 === "Linux/Mac"
 
-    <div class="termy">
     ```bash
     docker run -p 5000:80 -e SCRIPT_NAME='/mypygeoapi' \
     -v $(pwd)/my.config.yml:/pygeoapi/local.config.yml -it geopython/pygeoapi
     # navegue para http://localhost:5000/mypygeoapi
     ```
-    </div>
 
 === "Windows (PowerShell)"
 
-    <div class="termy">
     ```bash
     docker run -p 5000:80 -e SCRIPT_NAME='/mypygeoapi' -v ${pwd}/my.config.yml:/pygeoapi/local.config.yml -it geopython/pygeoapi
     # navegue para http://localhost:5000/mypygeoapi
     ```
-    </div>
 
 # Resumo
 
-Parabéns! Agora pode implementar a pygeoapi como um serviço cloud native.
+Parabéns! Agora pode implementar a pygeoapi como um serviço cloud native.

workshop/content/docs/advanced/i18n.md

@@ -52,37 +52,29 @@ Babel provides a utility which extracts all keys to be translated from the templ
 
 === "Linux/Mac"
 
-    <div class="termy">
     ```bash
     pybabel extract -F babel-mapping.ini -o locale/messages.pot ./
     ```
-    </div>
 
 === "Windows (PowerShell)"
 
-    <div class="termy">
     ```bash
     pybabel extract -F babel-mapping.ini -o locale/messages.pot ./
     ```
-    </div>
 
 The resulting `.pot` file is used to create or update existing `.po` files, which exist for each language, containing the actual translations.
 
 === "Linux/Mac"
 
-    <div class="termy">
     ```bash
     pybabel init -d locale -l it -i locale/messages.pot
     ```
-    </div>
 
 === "Windows (PowerShell)"
 
-    <div class="termy">
     ```bash
     pybabel init -d locale -l it -i locale/messages.pot
     ```
-    </div>
 
 The `.po` files are stored in pygeoapi's source code repository on GitHub. You can create a Pull Request to add or update your favourite languages. `.po` files can also be added to translation software such as [transifex.com](https://transifex.com). 
 

workshop/content/docs/advanced/i18n.pt.md

@@ -52,37 +52,29 @@ O Babel fornece um utilitário que extrai todas as chaves a serem traduzidas dos
 
 === "Linux/Mac"
 
-    <div class="termy">
     ```bash
     pybabel extract -F babel-mapping.ini -o locale/messages.pot ./
     ```
-    </div>
 
 === "Windows (PowerShell)"
 
-    <div class="termy">
     ```bash
     pybabel extract -F babel-mapping.ini -o locale/messages.pot ./
     ```
-    </div>
 
 O ficheiro `.pot` resultante é usado para criar ou atualizar ficheiros `.po` existentes, que existem para cada língua, contendo as traduções atuais.
 
 === "Linux/Mac"
 
-    <div class="termy">
     ```bash
     pybabel init -d locale -l it -i locale/messages.pot
     ```
-    </div>
 
 === "Windows (PowerShell)"
 
-    <div class="termy">
     ```bash
     pybabel init -d locale -l it -i locale/messages.pot
     ```
-    </div>
 
 Os ficheiros `.po` são armazenados no repositório de código fonte da pygeoapi no GitHub. Pode criar um Pull Request para adicionar ou atualizar as suas linguagens favoritas. Os ficheiros `.po` também podem ser adicionados a software de tradução como [transifex.com](https://transifex.com). 
 
@@ -111,4 +103,4 @@ A pygeoapi inclui um mecanismo para influenciar as respostas da API baseado na l
 
 # Resumo
 
-Parabéns! Personalizámos a pygeoapi para suportar múltiplas línguas.
+Parabéns! Personalizámos a pygeoapi para suportar múltiplas línguas.

workshop/content/docs/advanced/inspire.md

@@ -54,19 +54,15 @@ recommendation and the relevant Good Practices.
 
     === "Linux/Mac"
 
-        <div class="termy">
         ```bash
         python3 load_tinydb_records.py <path/to/xml-files> <output.db>
         ```
-        </div>
 
     === "Windows (PowerShell)"
 
-        <div class="termy">
         ```bash
         python3 load_tinydb_records.py <path/to/xml-files> <output.db>
         ```
-        </div>
 
     Now configure [TinyDB as a provider for OGC API - Records](https://docs.pygeoapi.io/en/latest/data-publishing/ogcapi-records.html#tinydbcatalogue). Restart the service and verify the result. Verify also the XML output of some of the records.