Fix rtd build, improvements in task running

.readthedocs.yaml

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

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)

docs/requirements.txt

@@ -1,23 +0,0 @@
-jupyter-book
-numba
-numpy>=1.20
-sphinx<7
-sphinxcontrib-bibtex
-sphinx_rtd_theme>=0.5.1
-sphinx-togglebutton
-sphinx-copybutton
-sphinx-thebe
-sphinx-comments
-sphinx-design
-sphinx-book-theme
-sphinx-jupyterbook-latex
-sphinxcontrib-bibtex
-tensorboard
-torch
-tqdm
-protobuf
-pettingzoo
-nbsphinx
-recommonmark
-poetry
-myst-nb

poetry.lock

@@ -5869,4 +5869,4 @@ pybullet = ["pybullet"]
 [metadata]
 lock-version = "2.0"
 python-versions = "^3.11"
-content-hash = "e5d2151b881b6c2d11f44b362555c763911060145d47a01ac1fa8f95ef78d73b"
+content-hash = "375a3ce85cefea9ee4ec3dc062bcc3486c8b790768e70cca4d0ac779d0217547"

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/*"
+clean-nbs = "python docs/nbstripout.py"
-format = ["_black_format", "_ruff_format", "_poetry_install_sort_plugin", "_poetry_sort", "_clean-nbs"]
+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"]