#2472: switch to using nbsphinx + added readme steps to setup pandoc + revert changes

docs/Makefile

@@ -6,8 +6,6 @@ SPHINXBUILD   ?= sphinx-build
 SOURCEDIR     = .
 BUILDDIR      = _build
 
-JUPYTEROUTPUTPATH="_static\notebooks\html"
-
 # Remove command is different depending on OS
 ifdef OS
 	RM = IF exist $(AUTOSUMMARY) (  RMDIR $(AUTOSUMMARY) /s /q )
@@ -31,8 +29,4 @@ clean:
 %: Makefile | clean
 	pip-licenses --format=rst --with-urls --output-file=source/primaite-dependencies.rst
 
-    jupyter nbconvert --execute --to html --output-dir _static/notebooks/html ../src/primaite/**/*.ipynb
-
-    cp -r ../src/primaite/notebooks/_package_data _static/notebooks/html/_package_data _static/notebooks/html/_package_data
-
 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/conf.py

@@ -9,7 +9,9 @@ import datetime
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 import os
+import shutil
 import sys
+from pathlib import Path
 from typing import Any
 
 import furo  # noqa
@@ -43,11 +45,12 @@ html_title = f"{project} v{release} docs"
 # ones.
 extensions = [
     "sphinx.ext.autodoc",  # Core Sphinx library for auto html doc generation from docstrings
-    "sphinx.ext.autosummary",  # Create summary tables for modules/classes/methods etc
+    # "sphinx.ext.autosummary",  # Create summary tables for modules/classes/methods etc
     "sphinx.ext.intersphinx",  # Link to other project's documentation (see mapping below)
     "sphinx.ext.viewcode",  # Add a link to the Python source code for classes, functions etc.
     "sphinx.ext.todo",
     "sphinx_copybutton",  # Adds a copy button to code blocks
+    "nbsphinx",
 ]
 
 templates_path = ["_templates"]
@@ -64,33 +67,7 @@ html_theme = "furo"
 html_static_path = ["_static"]
 html_theme_options = {"globaltoc_collapse": True, "globaltoc_maxdepth": 2}
 html_copy_source = False
-
-
-def get_notebook_links() -> str:
-    """
-    Returns a string which will be added to the RST.
-
-    Allows for dynamic addition of notebooks to the documentation.
-    """
-    notebooks = os.listdir("_static/notebooks/html")
-
-    links = []
-    links.append("<ul>")
-    for notebook in notebooks:
-        if notebook == "notebook_links.html":
-            continue
-        notebook_link = (
-            f'<li><a href="../_static/notebooks/html/{notebook}" target="blank">'
-            f"{notebook.replace('.html', '')}"
-            f"</a></li>\n"
-        )
-        links.append(notebook_link)
-    links.append("<ul>")
-
-    with open("_static/notebooks/html/notebook_links.html", "w") as html_file:
-        html_file.write("".join(links))
-
-    return ":file: ../_static/notebooks/html/notebook_links.html"
+nbsphinx_allow_errors = True
 
 
 def replace_token(app: Any, docname: Any, source: Any):
@@ -103,12 +80,26 @@ def replace_token(app: Any, docname: Any, source: Any):
 
 tokens = {
     "{VERSION}": release,
-    "{NOTEBOOK_LINKS}": get_notebook_links(),
 }  # Token VERSION is replaced by the value of the PrimAITE version in the version file
 """Dict containing the tokens that need to be replaced in documentation."""
 
+temp_ignored_notebooks = ["Training-an-RLLib-Agent.ipynb", "Training-an-RLLIB-MARL-System.ipynb"]
+
+
+def copy_notebooks_to_docs():
+    """Copies the notebooks to a directory within docs directory so that they can be included."""
+    for notebook in Path("../src/primaite").rglob("*.ipynb"):
+        if notebook.name not in temp_ignored_notebooks:
+            dest = Path("source") / "notebooks"
+            Path(dest).mkdir(parents=True, exist_ok=True)
+            shutil.copy2(src=notebook, dst=dest)
+
+    # copy any images
+    # TODO
+
 
 def setup(app: Any):
     """Custom setup for sphinx."""
+    copy_notebooks_to_docs()
     app.add_config_value("tokens", {}, True)
     app.connect("source-read", replace_token)

docs/index.rst

@@ -115,7 +115,7 @@ Head over to the :ref:`getting-started` page to install and setup PrimAITE!
    :hidden:
 
    source/example_notebooks
-   source/executed_notebooks
+   source/notebooks/executed_notebooks
 
 .. toctree::
    :caption: Developer information:

docs/make.bat

@@ -9,9 +9,6 @@ REM Command file for Sphinx documentation
 if "%SPHINXBUILD%" == "" (
 	set SPHINXBUILD=sphinx-build
 )
-if "%JUPYTER%" == "" (
-	set JUPYTER=jupyter
-)
 set SOURCEDIR=.
 set BUILDDIR=_build
 
@@ -31,35 +28,14 @@ if errorlevel 9009 (
 	exit /b 1
 )
 
-%JUPYTER% >NUL 2>NUL
-if errorlevel 9009 (
-	echo.
-	echo.'jupyter' command was not found. Make sure you have Jupyter
-	echo.installed, then set the JUPYTER environment variable to point
-	echo.to the full path of the 'jupyter' executable.
-	exit /b 1
-)
-
 if "%1" == "" goto help
 
 REM delete autosummary if it exists
 
-IF EXIST %AUTOSUMMARYDIR% (
-    echo deleting %AUTOSUMMARYDIR%
-    RMDIR %AUTOSUMMARYDIR% /s /q
-)
-
-REM delete notebook if it exists
-IF EXIST %JUPYTEROUTPUTPATH% (
-    echo deleting %JUPYTEROUTPUTPATH%
-    RMDIR %JUPYTEROUTPUTPATH% /s /q
-)
-
-REM run and print html of notebooks
-JUPYTER nbconvert --execute --to html --output-dir %JUPYTEROUTPUTPATH% "%cd%\..\src\primaite\**\*.ipynb"
-
-REM copy notebook image dependencies
-robocopy ..\src\primaite\notebooks\_package_data _static\notebooks\html\_package_data
+@REM IF EXIST %AUTOSUMMARYDIR% (
+@REM     echo deleting %AUTOSUMMARYDIR%
+@REM     RMDIR %AUTOSUMMARYDIR% /s /q
+@REM )
 
 REM print the YT licenses
 set LICENSEBUILD=pip-licenses --format=rst --with-urls
@@ -74,15 +50,10 @@ goto end
 %SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
 
 :clean
-IF EXIST %AUTOSUMMARYDIR% (
-    echo deleting %AUTOSUMMARYDIR%
-    RMDIR %AUTOSUMMARYDIR% /s /q
-)
-
-IF EXIST %JUPYTEROUTPUTPATH% (
-    echo deleting %JUPYTEROUTPUTPATH%
-    RMDIR %JUPYTEROUTPUTPATH% /s /q
-)
+@REM IF EXIST %AUTOSUMMARYDIR% (
+@REM     echo deleting %AUTOSUMMARYDIR%
+@REM     RMDIR %AUTOSUMMARYDIR% /s /q
+@REM )
 
 :end
 popd

docs/source/notebooks/executed_notebooks.rst

@@ -9,5 +9,8 @@ Executed Jupyter Notebooks
 
 Below is a list of available pre-executed notebooks.
 
-.. raw:: html
-    {NOTEBOOK_LINKS}
+.. toctree::
+    :maxdepth: 1
+    :glob:
+
+    *