From 190a5d9bb12624f6e1c1427222ae0bf0e5f5b584 Mon Sep 17 00:00:00 2001 From: Alexander Goscinski Date: Tue, 10 Sep 2024 06:47:52 +0200 Subject: [PATCH 01/10] 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. --- docs/Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/Makefile b/docs/Makefile index ea5e9afe..c43b2e9d 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -56,7 +56,7 @@ cleannotebooks: # -W: exit on warning defaultdoc: - $(SPHINXBUILD) -b html -nW $(ALLSPHINXOPTS) $(BUILDDIR)/html + $(SPHINXBUILD) -b html -n $(ALLSPHINXOPTS) $(BUILDDIR)/html all: html latexpdf From e6c82f3d9c34d44a39b80d6be82dafe71c6b5b0e Mon Sep 17 00:00:00 2001 From: Alexander Goscinski Date: Tue, 10 Sep 2024 06:56:03 +0200 Subject: [PATCH 02/10] Relax dependency requirements The current pinned version in the requirements do not work anymore so all pinning of versions have been removed. --- requirements.txt | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/requirements.txt b/requirements.txt index 0d558b62..9d675eef 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,7 +1,7 @@ -jinja2~=3.0 -Sphinx~=4.1 +jinja2 +Sphinx sphinx-book-theme -sphinx-copybutton~=0.4.0 +sphinx-copybutton sphinx-panels sphinx-tabs -myst-nb==0.16.0 +myst-nb From 51c142d15741174f1602163a9ebc1496521e0ab1 Mon Sep 17 00:00:00 2001 From: Alexander Goscinski Date: Tue, 10 Sep 2024 07:12:01 +0200 Subject: [PATCH 03/10] Fix linkchecks - pipx has been updated - virtual box does not work for the moment so we have to ignore it. - 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 --- docs/conf.py | 2 ++ docs/sections/getting_started/setup.md | 2 +- docs/sections/writing_workflows/validation.md | 2 +- 3 files changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 45119936..29f6ee36 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -390,6 +390,8 @@ suppress_warnings = ["misc.highlighting_failure"] +# Links we ignore, because they do not work temporary and we cannot fix it +linkcheck_ignore = ["https://www.virtualbox.org/", "https://www.big-map.eu/"] def setup(app): """Setup function called by sphinx.""" diff --git a/docs/sections/getting_started/setup.md b/docs/sections/getting_started/setup.md index dd445e6b..1f3590d8 100644 --- a/docs/sections/getting_started/setup.md +++ b/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 diff --git a/docs/sections/writing_workflows/validation.md b/docs/sections/writing_workflows/validation.md index 5da0c965..a897b551 100644 --- a/docs/sections/writing_workflows/validation.md +++ b/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/). ::: From 5d911baa3538e546d9388b662c17f04591a65025 Mon Sep 17 00:00:00 2001 From: Alexander Goscinski Date: Tue, 10 Sep 2024 07:35:45 +0200 Subject: [PATCH 04/10] Update pre-commits hook and run formatter Update to python 3.11 and update sphinx and subsequent dependencies. --- .pre-commit-config.yaml | 6 +++--- docs/conf.py | 1 + 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index e8b4253f..a8d24b1a 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -16,11 +16,11 @@ repos: rev: '22.6.0' hooks: - id: black - language_version: python3.8 + language_version: python3.11 - 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 diff --git a/docs/conf.py b/docs/conf.py index 29f6ee36..2110796e 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -393,6 +393,7 @@ # Links we ignore, because they do not work temporary and we cannot fix it linkcheck_ignore = ["https://www.virtualbox.org/", "https://www.big-map.eu/"] + def setup(app): """Setup function called by sphinx.""" app.add_css_file("css/custom.css") From a2244e92aff46fe23cad73a7f9d32e9c817a7326 Mon Sep 17 00:00:00 2001 From: Alexander Goscinski Date: Tue, 10 Sep 2024 07:17:30 +0200 Subject: [PATCH 05/10] Add OS to RTD config --- .readthedocs.yml | 3 +++ 1 file changed, 3 insertions(+) diff --git a/.readthedocs.yml b/.readthedocs.yml index f0a60518..26c4885a 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -4,6 +4,9 @@ # Required version: 2 +build: + os: "ubuntu-22.04" + # Build documentation in the docs/ directory with Sphinx sphinx: configuration: docs/conf.py From ec9e5bde5d41af9cf625d3aa7c9428c4ff2c240b Mon Sep 17 00:00:00 2001 From: Alexander Goscinski Date: Tue, 10 Sep 2024 07:36:15 +0200 Subject: [PATCH 06/10] Update how to specify python in the RTD config and version RTD wants that the version is now specified in the build.tools. Updated to python 3.12 --- .readthedocs.yml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/.readthedocs.yml b/.readthedocs.yml index 26c4885a..0fd6f0e3 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -6,6 +6,8 @@ version: 2 build: os: "ubuntu-22.04" + tools: + python: "3.12" # Build documentation in the docs/ directory with Sphinx sphinx: @@ -19,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 From 96609cceec2e5e102d38ac146d48bc0695bf4fa3 Mon Sep 17 00:00:00 2001 From: Alexander Goscinski Date: Tue, 10 Sep 2024 07:51:11 +0200 Subject: [PATCH 07/10] Remove pinned python version for black Uses latest version, also the python version should not matter for a formatter. --- .pre-commit-config.yaml | 1 - 1 file changed, 1 deletion(-) diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index a8d24b1a..6b8052d3 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -16,7 +16,6 @@ repos: rev: '22.6.0' hooks: - id: black - language_version: python3.11 - repo: https://github.com/myint/rstcheck rev: v6.2.4 From 5387dc499edf00993aa74de29a2abd266bda28ad Mon Sep 17 00:00:00 2001 From: Alexander Goscinski Date: Tue, 10 Sep 2024 07:54:45 +0200 Subject: [PATCH 08/10] Update versions in the CI to Python 3.8 --- .github/workflows/ci.yml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 7af71345..75516dd8 100644 --- a/.github/workflows/ci.yml +++ b/.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 From ed26387f58de52dc648eb6604c64f099d06bf85c Mon Sep 17 00:00:00 2001 From: Alexander Goscinski Date: Wed, 11 Sep 2024 11:27:28 +0200 Subject: [PATCH 09/10] Apply suggestions from code review --- docs/Makefile | 2 +- docs/conf.py | 2 +- requirements.txt | 12 ++++++------ 3 files changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/Makefile b/docs/Makefile index c43b2e9d..76257dff 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -56,7 +56,7 @@ cleannotebooks: # -W: exit on warning defaultdoc: - $(SPHINXBUILD) -b html -n $(ALLSPHINXOPTS) $(BUILDDIR)/html + $(SPHINXBUILD) -b html -T -W --keep-going $(ALLSPHINXOPTS) $(BUILDDIR)/html all: html latexpdf diff --git a/docs/conf.py b/docs/conf.py index 2110796e..3cf19061 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -391,7 +391,7 @@ suppress_warnings = ["misc.highlighting_failure"] # Links we ignore, because they do not work temporary and we cannot fix it -linkcheck_ignore = ["https://www.virtualbox.org/", "https://www.big-map.eu/"] +linkcheck_ignore = ["https://www.big-map.eu/"] def setup(app): diff --git a/requirements.txt b/requirements.txt index 9d675eef..eabfbc01 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,7 +1,7 @@ -jinja2 -Sphinx -sphinx-book-theme -sphinx-copybutton -sphinx-panels -sphinx-tabs +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 From d91df6e25ebc3909cf86575ec255316b4a40c91b Mon Sep 17 00:00:00 2001 From: Alexander Goscinski Date: Wed, 11 Sep 2024 11:27:40 +0200 Subject: [PATCH 10/10] Apply suggestions from code review --- requirements.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/requirements.txt b/requirements.txt index eabfbc01..be019ba1 100644 --- a/requirements.txt +++ b/requirements.txt @@ -4,4 +4,4 @@ sphinx-book-theme~=1.1.3 sphinx-copybutton~=0.5.2 sphinx-panels~=0.4.1 sphinx-tabs~=3.4.5 -myst-nb +myst-nb~=1.1.1