Update build to fix CI (#472)

* Treat warnings not anymore as errors

There are some sphinx internal warnings that are time consuming to debug
and don't affect the quality of the tutorial page, so we ignore them by
treating warnings as warnings. This is in already done by RTD with the
`--keep-going` flag

* Relax dependency requirements

The current pinned version in the requirements do not work anymore so
new version have been pinned.

* Fix linkchecks

- pipx has been updated
- the underscore explanation link works but somehow is marked as broken
  so we replace with an explanation from realpython
- big-map.eu does not work but is sponsor so cannot be replaced/removed

* Update pre-commits hook and run formatter

Update to python 3.11 and update sphinx and subsequent dependencies.

* Add OS to RTD config

* Update how python is specified in the RTD config and version

RTD wants that the version is now specified in the build.tools.

Updated to python 3.12

* Remove pinned python version for black

Uses latest version, also the python version should not matter for a
formatter.

* Update versions in the CI to Python 3.12

Author: agoscinski

.github/workflows/ci.yml

@@ -11,10 +11,10 @@ jobs:
 
     steps:
     - uses: actions/checkout@v2
-    - name: Set up Python 3.8
+    - name: Set up Python 3.12
       uses: actions/setup-python@v2
       with:
-        python-version: 3.8
+        python-version: 3.12
     - uses: pre-commit/action@v2.0.0
 
   build:
@@ -24,10 +24,10 @@ jobs:
 
     steps:
     - uses: actions/checkout@v2
-    - name: Set up Python 3.8
+    - name: Set up Python 3.12
       uses: actions/setup-python@v2
       with:
-        python-version: 3.8
+        python-version: 3.12
     - name: Install python dependencies
       run: |
         pip install --upgrade pip

.pre-commit-config.yaml

@@ -16,11 +16,10 @@ repos:
       rev: '22.6.0'
       hooks:
       - id: black
-        language_version: python3.8
 
   - repo: https://github.com/myint/rstcheck
-    rev: v6.1.0
+    rev: v6.2.4
     hooks:
     - id: rstcheck
       additional_dependencies:
-        - sphinx==4.1.2
+        - sphinx~=8.0.0

.readthedocs.yml

@@ -4,6 +4,11 @@
 # Required
 version: 2
 
+build:
+  os: "ubuntu-22.04"
+  tools:
+    python: "3.12"
+
 # Build documentation in the docs/ directory with Sphinx
 sphinx:
   configuration: docs/conf.py
@@ -16,6 +21,5 @@ formats: []
 
 # Optionally set the version of Python and requirements required to build your docs
 python:
-  version: "3.8"
   install:
     - requirements: requirements.txt

docs/Makefile

@@ -56,7 +56,7 @@ cleannotebooks:
 
 # -W: exit on warning
 defaultdoc:
-	$(SPHINXBUILD) -b html -nW $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	$(SPHINXBUILD) -b html -T -W --keep-going $(ALLSPHINXOPTS) $(BUILDDIR)/html
 
 all: html latexpdf
 

docs/conf.py

@@ -390,6 +390,9 @@
 
 suppress_warnings = ["misc.highlighting_failure"]
 
+# Links we ignore, because they do not work temporary and we cannot fix it
+linkcheck_ignore = ["https://www.big-map.eu/"]
+
 
 def setup(app):
     """Setup function called by sphinx."""

docs/sections/getting_started/setup.md

@@ -29,7 +29,7 @@ AiiDAlab Launch makes it easy to run AiiDA on your own workstation or laptop.
 To use AiiDAlab launch you will have to
 
 1. [Install Docker on your workstation or laptop](https://docs.docker.com/get-docker/) and [Manage Docker as a non-root user](https://docs.docker.com/engine/install/linux-postinstall/).
-2. Install AiiDAlab launch with [pipx](https://pypa.github.io/pipx/installation/) (**recommended**):
+2. Install AiiDAlab launch with [pipx](https://pipx.pypa.io/stable/installation/) (**recommended**):
 
    ```console
    pipx install aiidalab-launch

docs/sections/writing_workflows/validation.md

@@ -90,7 +90,7 @@ You can read about the ports and port namespace concepts in the [AiiDA documenta
 {{ python }} **The underscore `_` character**
 
 The underscore character has quite a lot interesting use cases in Python!
-You can find out more about them [here](https://www.datacamp.com/tutorial/role-underscore-python).
+You can find out more about them [here](https://realpython.com/python-double-underscore/).
 
 :::
 

requirements.txt

@@ -1,7 +1,7 @@
-jinja2~=3.0
-Sphinx~=4.1
-sphinx-book-theme
-sphinx-copybutton~=0.4.0
-sphinx-panels
-sphinx-tabs
-myst-nb==0.16.0
+jinja2~=3.1.4
+Sphinx~=8.0.2
+sphinx-book-theme~=1.1.3
+sphinx-copybutton~=0.5.2
+sphinx-panels~=0.4.1
+sphinx-tabs~=3.4.5
+myst-nb~=1.1.1