Add Sphinx-based docs including a markdown version of the vocabulary guidelines v2.0

.github/dependabot.yml

@@ -0,0 +1,6 @@
+version: 2
+updates:
+- package-ecosystem: github-actions
+  directory: "/"
+  schedule:
+    interval: monthly

.github/workflows/ci-pr.yml

@@ -30,7 +30,7 @@ jobs:
 
     steps:
       - name: Checkout PR branch into cwd
-        uses: actions/checkout@v4
+        uses: actions/checkout@d632683dd7b4114ad314bca15554477dd762a938
         with:
           # Checkout the fork/head-repository to push changes to the fork.
           # Without this the base repository will be checked out and committed to.
@@ -40,7 +40,7 @@ jobs:
           ref: ${{ github.head_ref }}
 
       - name: Checkout main branch into directory _main_branch/
-        uses: actions/checkout@v4
+        uses: actions/checkout@d632683dd7b4114ad314bca15554477dd762a938
         with:
           ref: main
           path: _main_branch
@@ -49,9 +49,9 @@ jobs:
             vocabularies/
           fetch-depth: 1
 
-      - uses: actions/setup-python@v5
+      - uses: actions/setup-python@f677139bbe7f9c59b41e40162b753c062f5d49a3
         with:
-          python-version: '3.11'
+          python-version: '3.12'
 
       - name: Install dependencies
         run: |

.github/workflows/merge.yml

@@ -31,21 +31,21 @@ jobs:
     runs-on: ubuntu-latest
     timeout-minutes: 10
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@d632683dd7b4114ad314bca15554477dd762a938
         with:
           # Using fetch-depth 0 is the only way to get all tags which are needed for building docs.
           fetch-depth: 0
 
       - name: Checkout gh-pages branch to dir publish/
-        uses: actions/checkout@v4
+        uses: actions/checkout@d632683dd7b4114ad314bca15554477dd762a938
         with:
           ref: gh-pages
           path: publish
           fetch-depth: 1
 
-      - uses: actions/setup-python@v5
+      - uses: actions/setup-python@f677139bbe7f9c59b41e40162b753c062f5d49a3
         with:
-          python-version: '3.11'
+          python-version: '3.12'
 
       - name: Install dependencies
         run: |
@@ -75,7 +75,7 @@ jobs:
           # Build joined turtle
           voc4cat transform --logfile publish/dev/voc4cat.log --join publish/dev/
 
-      - name: Run voc4cat (build HTML documentation)
+      - name: Run voc4cat (build pyLODE HTML documentation)
         run: |
           voc4cat docs --force --logfile publish/dev/voc4cat.log publish/dev/
           # move versions-overview to what becomes gh-pages root
@@ -89,6 +89,13 @@ jobs:
         run: |
           voc4cat convert --logfile publish/dev/voc4cat.log --outputformat xml publish/dev/voc4cat.xlsx
 
+      - name: Build Sphinx documentation (website)
+        run: |
+          python -VV
+          python -m pip install -r docs/requirements.txt --force
+          sphinx-build --nitpicky --fail-on-warning --keep-going docs docs/_build
+          cp -r docs/_build/. publish/
+
       - name: Deploy updated gh-pages content
         # This replaces all prior content in gh-pages branch. But we have
         # checked out the gh-pages branch above so that we keep all prior
@@ -106,10 +113,11 @@ jobs:
         # This step is not required and may be removed.
         # It may be helpful for trouble shooting.
         if: ${{ always() }}
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@50769540e7f4bd5e21e526ee35c689e35e0d6874
         with:
           name: voc4cat-pages-dev-content
           path: publish/
+          retention-days: 5
 
 # Lit:
 # https://github.com/peaceiris/actions-gh-pages

.github/workflows/publish.yml

@@ -31,21 +31,21 @@ jobs:
     runs-on: ubuntu-latest
     timeout-minutes: 10
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@d632683dd7b4114ad314bca15554477dd762a938
         with:
           # Using fetch-depth 0 is the only way to get all tags which are needed for building docs.
           fetch-depth: 0
 
       - name: Checkout gh-pages branch to dir publish/
-        uses: actions/checkout@v4
+        uses: actions/checkout@d632683dd7b4114ad314bca15554477dd762a938
         with:
           ref: gh-pages
           path: publish
           fetch-depth: 1
 
-      - uses: actions/setup-python@v5
+      - uses: actions/setup-python@f677139bbe7f9c59b41e40162b753c062f5d49a3
         with:
-          python-version: '3.11'
+          python-version: '3.12'
 
       - name: Install dependencies
         run: |
@@ -73,7 +73,7 @@ jobs:
           # Build joined turtle
           voc4cat transform --logfile publish/latest/voc4cat.log --join publish/latest/
 
-      - name: Run voc4cat (build HTML documentation)
+      - name: Run voc4cat (build pyLODE HTML documentation)
         run: |
           voc4cat docs --force --logfile publish/latest/voc4cat.log publish/latest/
           # move versions-overview to what becomes gh-pages root
@@ -92,6 +92,13 @@ jobs:
           mkdir -p publish/${{ github.ref_name }}
           cp -r publish/latest/. publish/${{ github.ref_name }}/
 
+      - name: Build Sphinx documentation (website)
+        run: |
+          python -VV
+          python -m pip install -r docs/requirements.txt --force
+          sphinx-build --nitpicky --fail-on-warning --keep-going docs docs/_build
+          cp -r docs/_build/. publish/
+
       - name: Deploy updated gh-pages content
         # This replaces all prior content in gh-pages branch. But we have
         # checked out the gh-pages branch above so that we keep all prior
@@ -106,12 +113,13 @@ jobs:
 
       - name: Store publish dir (=pages) as artifact
         # This step is not required and may be removed.
-        # It may be helpful for trouble shooting.
+        # It may be helpful for troubleshooting.
         if: ${{ always() }}
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@50769540e7f4bd5e21e526ee35c689e35e0d6874
         with:
           name: voc4cat-pages-release-${{ github.ref_name }}
           path: publish/
+          retention-days: 5
 
 # Lit:
 # https://github.com/peaceiris/actions-gh-pages

.markdownlint.jsonc

@@ -0,0 +1,14 @@
+/*
+Configuration file for VSCode-markdownlint extension,
+see https://github.com/DavidAnson/vscode-markdownlint#configure
+
+For how the rules can be configured,
+see https://github.com/DavidAnson/markdownlint/blob/v0.35.0/schema/.markdownlint.jsonc
+*/
+{
+  "default": true,
+  "MD013": {
+    "line_length": 160  // Allow longer lines
+  },
+  "MD034": false,
+}

_typos.toml

@@ -0,0 +1,4 @@
+# Config for the spell checker https://github.com/crate-ci/typos
+[default.extend-words]
+# Don't correct the surname "Linke"
+linke = "linke"

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/README.md

@@ -0,0 +1,10 @@
+# Guidelines and Maintenance Documentation
+
+We use [Sphinx](https://www.sphinx-doc.org/) as documentation builder with the [furo](https://github.com/pradyunsg/furo) theme
+and [MySt](https://mystmd.org/) to support extended markdown.
+
+To get an overview about the styling features supported visit the [furo theme documentation](https://pradyunsg.me/furo/kitchen-sink/)
+or the [MyST authoring documentation](https://mystmd.org/guide/typography).
+
+You may wonder why the sub-folders here have a `docs_` prefix.
+This is to clearly distinguish them from the pyLODE-vocabulary documentation after deployment to gh-pages.