feat: add feedback as part of discussions #21

docs/source/_jupyter/content/local-file.txt

@@ -0,0 +1 @@
+I'm Batman.

src/python/sandbox.ipynb → docs/source/_jupyter/content/runner.ipynb

@@ -6,7 +6,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "import numpy as np"
+    "print(\"This notebook is from local `content` folder\")"
    ]
   }
  ],
@@ -17,15 +17,7 @@
    "name": "python3"
   },
   "language_info": {
-   "codemirror_mode": {
-    "name": "ipython",
-    "version": 3
-   },
-   "file_extension": ".py",
-   "mimetype": "text/x-python",
    "name": "python",
-   "nbconvert_exporter": "python",
-   "pygments_lexer": "ipython3",
    "version": "3.12.6"
   }
  },

docs/source/_jupyter/repl/jupyter-lite.json

@@ -0,0 +1,12 @@
+{
+    "jupyter-lite-schema-version": 0,
+    "jupyter-config-data": {
+        "appName": "TOPSTSCHOOL Live Interpreter",
+        "disabledExtensions": [
+            "@jupyterlab/application-extension:logo",
+            "@jupyterlab/drawio-extension",
+            "jupyterlab-kernel-spy",
+            "jupyterlab-tour"
+        ]
+    }
+}

docs/source/_resources/external-resources.rst

@@ -1,6 +1,6 @@
 .. Author: Akshay Mestry <xa@mes3.dev>
 .. Created on: Monday, September 09 2024
-.. Last updated on: Monday, October 07 2024
+.. Last updated on: Wednesday, October 09 2024
 
 ===============================================================================
 External Resources
@@ -24,6 +24,6 @@ External Resources
 Sandbox |badge-beta|
 -------------------------------------------------------------------------------
 
-.. notebooklite:: ../../../src/python/sandbox.ipynb
-    :width: 100%
-    :height: 600px
+.. notebook::
+
+.. notebook:: runner.ipynb

docs/source/conf.py

@@ -4,7 +4,7 @@
 
 Author: Akshay Mestry <xa@mes3.dev>
 Created on: Saturday, August 17 2024
-Last updated on: Sunday, October 06 2024
+Last updated on: Wednesday, October 09 2024
 
 This file contains the configuration settings for building the TOPSTSCHOOL
 documentation using Sphinx, a popular Python documentation tool. Sphinx
@@ -28,10 +28,16 @@
 
 from __future__ import annotations
 
+import glob
+import os
+import shutil
 import subprocess
 import typing as t
 from datetime import datetime as dt
 
+from jupyterlite_sphinx import jupyterlite_sphinx
+from sphinx.application import Sphinx
+
 # -- General configurations ---------------------------------------------------
 extensions: list[str] = [
     "jupyterlite_sphinx",
@@ -117,16 +123,106 @@
 html_theme: t.Final[str] = "coeus_sphinx_theme"
 html_static_path: list[str] = ["_static"]
 html_css_files: list[str] = ["css/override.css"]
-html_context: dict[str, str] = {
-    "feedback_link": source
-    + (
-        "/issues/new"
-        "?labels=community,discussion needed,documentation,enhancement"
-        "miscellaneous,open science,question"
-        "&title=Feedback about documentation"
-    )
-}
+html_context: dict[str, str] = {"feedback_link": source + ("/discussions/44")}
 
 # -- Options for Jupyter Notebook Embedding -----------------------------------
 jupyterlite_bind_ipynb_suffix: bool = False
 jupyterlite_silence: bool = True
+jupyterlite_dir: str = "_jupyter"
+
+
+def topst_jupyterlite_build(app: Sphinx, error: t.Any) -> None:
+    """Monkey-patched Jupyterlite build."""
+    if error is not None:
+        return
+
+    if app.builder.format == "html":
+        jupyterlite_config = app.env.config.jupyterlite_config
+        jupyterlite_contents = app.env.config.jupyterlite_contents
+        jupyterlite_dir = str(app.env.config.jupyterlite_dir)
+        jupyterlite_build_command_options: dict[str, t.Any] = (
+            app.env.config.jupyterlite_build_command_options
+        )
+        config = []
+        if jupyterlite_config:
+            config = ["--config", jupyterlite_config]
+        if jupyterlite_contents is None:
+            jupyterlite_contents = []
+        elif isinstance(jupyterlite_contents, str):
+            jupyterlite_contents = [jupyterlite_contents]
+        jupyterlite_contents = [
+            match
+            for pattern in jupyterlite_contents
+            for match in glob.glob(pattern, recursive=True)
+        ]
+        contents = []
+        for content in jupyterlite_contents:
+            contents.extend(["--contents", content])
+        apps_option = []
+        for liteapp in [
+            "notebooks",
+            "edit",
+            "lab",
+            "repl",
+            "tree",
+            "consoles",
+        ]:
+            apps_option.extend(["--apps", liteapp])
+        voici = None
+        if voici is not None:
+            apps_option.extend(["--apps", "voici"])
+        lite_dir = os.path.join(app.srcdir, jupyterlite_dir)
+        if not os.path.exists(lite_dir):
+            os.makedirs(lite_dir, exist_ok=True)
+        command = [
+            "jupyter",
+            "lite",
+            "build",
+            "--debug",
+            *config,
+            *contents,
+            "--contents",
+            os.path.join(lite_dir, "content"),
+            "--output-dir",
+            os.path.join(app.outdir, jupyterlite_dir),
+            *apps_option,
+            "--lite-dir",
+            lite_dir,
+        ]
+        if jupyterlite_build_command_options is not None:
+            for key, value in jupyterlite_build_command_options.items():
+                if key in ["contents", "output-dir", "lite-dir"]:
+                    raise RuntimeError("These options are not supported")
+                command.extend([f"--{key}", str(value)])
+        assert all(
+            [isinstance(s, str) for s in command]
+        ), f"Expected all commands arguments to be a str, got {command}"
+        kwargs: dict[str, t.Any] = {}
+        if app.env.config.jupyterlite_silence:
+            kwargs["stdout"] = subprocess.PIPE
+            kwargs["stderr"] = subprocess.PIPE
+        completed_process: subprocess.CompletedProcess[bytes] = subprocess.run(
+            command, cwd=app.srcdir, check=True, **kwargs
+        )
+        if completed_process.returncode != 0:
+            if app.env.config.jupyterlite_silence:
+                print(
+                    "Command `jupyterlite build` failed but its output has "
+                    "been silenced. stdout and stderr are reproduced below.\n"
+                )
+                print("stdout:", completed_process.stdout.decode())
+                print("stderr:", completed_process.stderr.decode())
+            raise subprocess.CalledProcessError(
+                returncode=completed_process.returncode,
+                cmd=command,
+                output=completed_process.stdout,
+                stderr=completed_process.stderr,
+            )
+    try:
+        shutil.rmtree(os.path.join(app.srcdir, "_contents"))
+        os.remove(os.path.join(app.srcdir, ".jupyterlite.doit.db"))
+    except FileNotFoundError:
+        pass
+
+
+jupyterlite_sphinx.jupyterlite_build = topst_jupyterlite_build