Fix rtd build, improvements in task running

.readthedocs.yaml

@@ -10,18 +10,14 @@ build:
   os: ubuntu-22.04
   tools:
     python: "3.11"
-  jobs:
-    pre_build:
-      - poetry config virtualenvs.create false
-      - poetry install --with dev
-    pre_install:
-      - poe run doc-generate-files
-
-      # Build documentation in the docs/ directory with Sphinx
-sphinx:
-  configuration: docs/conf.py
-# We recommend specifying your dependencies to enable reproducible builds:
-# https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
-python:
-  install:
-    - requirements: docs/requirements.txt
+  commands:
+    - mkdir -p $READTHEDOCS_OUTPUT/html
+    - curl -sSL https://install.python-poetry.org | python -
+#    - ~/.local/bin/poetry config virtualenvs.create false
+    - ~/.local/bin/poetry install --with dev
+##   Same as poe tasks, but unfortunately poe doesn't work with poetry not creating virtualenvs
+    - ~/.local/bin/poetry run python docs/autogen_rst.py
+    - ~/.local/bin/poetry run which jupyter-book
+    - ~/.local/bin/poetry run python docs/create_toc.py
+    - ~/.local/bin/poetry run jupyter-book config sphinx docs/
+    - ~/.local/bin/poetry run sphinx-build -W -b html docs $READTHEDOCS_OUTPUT/html

docs/_config.yml

@@ -20,7 +20,7 @@ only_build_toc_files        : false
 #######################################################################################
 # Execution settings
 execute:
-  execute_notebooks         : auto  # Whether to execute notebooks at build time. Must be one of ("auto", "force", "cache", "off")
+  execute_notebooks         : cache  # Whether to execute notebooks at build time. Must be one of ("auto", "force", "cache", "off")
   cache                     : ""    # A path to the jupyter cache that will be used to store execution artifacts. Defaults to `_build/.jupyter_cache/`
   exclude_patterns          : []    # A list of patterns to *skip* in execution (e.g. a notebook that takes a really long time)
   timeout                   : -1    # The maximum time (in seconds) each notebook cell is allowed to run.

docs/create_toc.py

@@ -0,0 +1,8 @@
+import os
+from pathlib import Path
+
+# This script provides a platform-independent way of making the jupyter-book call (used in pyproject.toml)
+toc_file = Path(__file__).parent / "_toc.yml"
+cmd = f"jupyter-book toc from-project docs -e .rst -e .md -e .ipynb  >{toc_file}"
+print(cmd)
+os.system(cmd)

docs/nbstripout.py

@@ -0,0 +1,10 @@
+"""Implements a platform-independent way of calling nbstripout (used in pyproject.toml)."""
+import glob
+import os
+from pathlib import Path
+
+if __name__ == "__main__":
+    docs_dir = Path(__file__).parent
+    for path in glob.glob(str(docs_dir / "02_notebooks" / "*.ipynb")):
+        cmd = f"nbstripout {path}"
+        os.system(cmd)

pyproject.toml

@@ -84,6 +84,11 @@ ray = { version = "^2", markers = "sys_platform != 'win32'" }
 ruff = "^0.0.285"
 scipy = "*"
 sphinx = "<7"
+sphinx-book-theme = "^1.0.1"
+sphinx-comments = "^0.0.3"
+sphinx-copybutton = "^0.5.2"
+sphinx-jupyterbook-latex = "^0.5.2"
+sphinx-togglebutton = "^0.3.2"
 sphinx-toolbox = "^3.5.0"
 sphinxcontrib-bibtex = "*"
 sphinxcontrib-spelling = "^8.0.0"
@@ -176,11 +181,11 @@ _ruff_format = "ruff --fix ."
 lint = ["_black_check", "_ruff_check"]
 _poetry_install_sort_plugin = "poetry self add poetry-plugin-sort"
 _poetry_sort = "poetry sort"
-_clean-nbs = "nbstripout docs/02_notebooks/*"
-format = ["_black_format", "_ruff_format", "_poetry_install_sort_plugin", "_poetry_sort", "_clean-nbs"]
+clean-nbs = "python docs/nbstripout.py"
+format = ["_black_format", "_ruff_format", "_poetry_install_sort_plugin", "_poetry_sort"]
 _autogen_rst = "python docs/autogen_rst.py"
 _sphinx_build = "sphinx-build -W -b html docs docs/_build"
-_jb_generate_toc = "bash -c \"jupyter-book toc from-project docs -e .rst -e .md -e .ipynb  > docs/_toc.yml \""
+_jb_generate_toc = "python docs/create_toc.py"
 _jb_generate_config = "jupyter-book config sphinx docs/"
 doc-clean = "rm -rf docs/_build"
 doc-generate-files = ["_autogen_rst", "_jb_generate_toc", "_jb_generate_config"]