Add Python-based tests for PDFs and rework CI

CI config now dry as a desert, with everything based around the (also improvided) Makefile(s)

.gitignore

@@ -1,3 +1,150 @@
+# ======================================================================================
+# Python (https://raw.githubusercontent.com/github/gitignore/master/Python.gitignore)
+# ======================================================================================
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# ======================================================================================
+# LaTeX
+# ======================================================================================
+
 # Generated PDF is not suitable for Git. We get our compiled PDF via CI.
 # Only ignore root level PDF, since images/vectors might be in PDF format.
 /*.pdf

.gitlab-ci.yml

@@ -1,4 +1,9 @@
-# Applies to all jobs, can be overridden in each
+# ======================================================================================
+# ======================================================================================
+# Global defaults, overwritable in each job
+# ======================================================================================
+# ======================================================================================
+
 default:
     image:
         # Image from dockerhub per default. Specify full path to use a different image.
@@ -11,7 +16,33 @@ default:
         # no entrypoint or that the entrypoint is prepared to start a shell command. ")
         # See also:
         # https://docs.gitlab.com/ee/ci/docker/using_docker_images.html#overriding-the-entrypoint-of-an-image
-        entrypoint: [ "" ]
+        entrypoint: [""]
+
+# ======================================================================================
+# ======================================================================================
+# Job templates (start with period).
+# Not actually run by the runner, but can be used to extend other jobs, keeping the
+# config dry.
+# The main logic happens here, the actual jobs only combine these as needed.
+# ======================================================================================
+# ======================================================================================
+
+.make: # Core job template
+    # Use make as the basis for all jobs. This allows to also easily run the steps
+    # offline/locally, as well as transition to other CI engines. All job names have to
+    # correspond to targets make knows about (see Makefile).
+    # Note we cannot have `default: script:`, so this approach works better.
+    script: make ${CI_JOB_NAME}
+
+.pdf: # Job template for PDF-producing jobs
+    extends: .make
+    stage: build
+    before_script:
+        # Make sure to clean any PDFs that might have crept in via the cache, forcing a
+        # remake at least once (otherwise, no remake might occur).
+        # It would be better to exclude the PDFs from the cache in the first place. This is
+        # not available yet, see: https://gitlab.com/gitlab-org/gitlab/-/issues/220017#note_440142507
+        - make clean-pdf
     # LaTeX and pandoc stages both provide PDFs:
     artifacts:
         # artifacts.zip is renamed to current tag/branch:
@@ -20,36 +51,58 @@ default:
             # Return all found *.pdf-files using wildcard.
             # For example, a thesis and the accompanying presentation.
             - "*.pdf"
-    # Run job 'only' if it fulfills certain criteria (BETTER: use `rules`):
-    # only:
-        # - tags
+
+.test:
+    extends: .make
+    stage: test
+    # Would be ideal to read the image tag from `pyproject.toml`, i.e. the poetry project
+    # file. See also: https://gitlab.com/gitlab-org/gitlab/-/issues/34202#note_444271649.
+    image: python:3.7.9
+    variables:
+        PIP_DOWNLOAD_DIR: ".pip"
     before_script:
-    # Make sure to clean any PDFs that might have crept in via the cache, forcing a
-    # remake at least once (otherwise, no remake might occur).
-    # It would be better to exclude the PDFs from the cache in the first place. This is
-    # not available yet, see: https://gitlab.com/gitlab-org/gitlab/-/issues/220017#note_440142507
-      - make clean-pdf
+        - cd tests
+        # Allow caching by only downloading first:
+        - pip download --dest=${PIP_DOWNLOAD_DIR} poetry
+        - pip install --find-links=${PIP_DOWNLOAD_DIR} poetry
+        # Make available for caching by installing to current directory:
+        - poetry config virtualenvs.in-project true
+        - poetry install -vv
+    cache:
+        untracked: true
+        key:
+            files:
+                # Cache is invalidated if any of these files changes, but also shared if
+                # these two files are equal.
+                - poetry.lock
+                - pyproject.toml
+
+# ======================================================================================
+# ======================================================================================
+# Actual job definitions.
+# All job names have to correspond to make targets, see .make above.
+# ======================================================================================
+# ======================================================================================
 
 preflight:
+    extends: .make
     stage: .pre
-    script:
-        - make preflight
     # Preflight checks are relevant, but we are interested in how exactly later jobs
     # error out if preflight fails. Therefore, allow failure.
     allow_failure: true
-    inherit:
-        # Do not inherit artifacts, this stage has none.
-        default: [image]
 
-build_latex:
-    stage: build
-    script:
-        - make tex
+tex:
+    extends: .pdf
     cache:
-      untracked: true
-      key: "$CI_JOB_NAME-$CI_COMMIT_REF_SLUG"
+        untracked: true
+        key: "$CI_JOB_NAME-$CI_COMMIT_REF_SLUG"
 
-build_pandoc:
-    stage: build
-    script:
-        - make README.pdf
+README.pdf:
+    extends: .pdf
+
+test-self:
+    extends: .test
+    needs: [] # Allows job to start immediately
+
+test-pdfs:
+    extends: .test