diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 1b34b7f..a93e455 100644 --- a/.readthedocs.yaml +++ b/.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 \ No newline at end of file + 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 diff --git a/docs/_config.yml b/docs/_config.yml index 89e4734..8169139 100644 --- a/docs/_config.yml +++ b/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. diff --git a/docs/create_toc.py b/docs/create_toc.py new file mode 100644 index 0000000..3e1779c --- /dev/null +++ b/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) diff --git a/docs/nbstripout.py b/docs/nbstripout.py new file mode 100644 index 0000000..95d4193 --- /dev/null +++ b/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) diff --git a/docs/requirements.txt b/docs/requirements.txt deleted file mode 100644 index fc91e0c..0000000 --- a/docs/requirements.txt +++ /dev/null @@ -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 \ No newline at end of file diff --git a/poetry.lock b/poetry.lock index 1471363..afa1a93 100644 --- a/poetry.lock +++ b/poetry.lock @@ -5869,4 +5869,4 @@ pybullet = ["pybullet"] [metadata] lock-version = "2.0" python-versions = "^3.11" -content-hash = "e5d2151b881b6c2d11f44b362555c763911060145d47a01ac1fa8f95ef78d73b" +content-hash = "375a3ce85cefea9ee4ec3dc062bcc3486c8b790768e70cca4d0ac779d0217547" diff --git a/pyproject.toml b/pyproject.toml index 66cfa33..a2d2c9e 100644 --- a/pyproject.toml +++ b/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"]