From 94d9686a1386f2283c436002bc955b2b677108ef Mon Sep 17 00:00:00 2001
From: mcbarton <150042563+mcbarton@users.noreply.github.com>
Date: Fri, 6 Dec 2024 19:41:14 +0000
Subject: [PATCH 1/9] Add docs PR preview

---
 .github/workflows/rtd-preview.yml |  24 ++++++
 .readthedocs.yaml                 |  11 +++
 docs/conf.py                      | 127 ++++++++++++++++++++++--------
 3 files changed, 129 insertions(+), 33 deletions(-)
 create mode 100644 .github/workflows/rtd-preview.yml

diff --git a/.github/workflows/rtd-preview.yml b/.github/workflows/rtd-preview.yml
new file mode 100644
index 000000000..f46f48c09
--- /dev/null
+++ b/.github/workflows/rtd-preview.yml
@@ -0,0 +1,24 @@
+name: RTD Preview
+on:
+  pull_request_target:
+    types: [opened]
+
+permissions:
+  pull-requests: write
+
+jobs:
+  binder:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Comment on the PR with the RTD preview
+        uses: actions/github-script@v7
+        with:
+          github-token: ${{secrets.GITHUB_TOKEN}}
+          script: |
+            var PR_NUMBER = context.issue.number
+            github.rest.issues.createComment({
+              issue_number: context.issue.number,
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              body: `https://jupyterlite--${PR_NUMBER}.org.readthedocs.build/en/${PR_NUMBER}/_static/lab/index.html :point_left: Try it on ReadTheDocs`
+            })
\ No newline at end of file
diff --git a/.readthedocs.yaml b/.readthedocs.yaml
index f51372140..43a496215 100644
--- a/.readthedocs.yaml
+++ b/.readthedocs.yaml
@@ -8,6 +8,17 @@ build:
   os: "ubuntu-22.04"
   tools:
     python: "3.11"
+  jobs:
+    pre_build:
+      - doit -n4 setup
+      - doit -n4 build
+      - doit -n4 docs:typedoc:mystify
+      - doit -n4 docs:app:pack
+      - doit -n4 dist
+  sphinx:
+    builder: html
+    configuration: docs/conf.py
+    fail_on_warning: true
   apt_packages:
     - clang-13
     - cmake
diff --git a/docs/conf.py b/docs/conf.py
index 78ced181f..08fd489a9 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -1,31 +1,69 @@
-# Configuration file for the Sphinx documentation builder.
-#
-# For the full list of built-in configuration values, see the documentation:
-# https://www.sphinx-doc.org/en/master/usage/configuration.html
+highlight_language = "C++"
+
+todo_include_todos = True
 
-# -- Project information -----------------------------------------------------
-# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+mathjax_path = "https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"
+
+# Add latex physics package
+mathjax3_config = {
+    "loader": {"load": ["[tex]/physics"]},
+    "tex": {"packages": {"[+]": ["physics"]}},
+}
 
+"""documentation for CppInterOp"""
+import datetime
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+from sphinx.application import Sphinx
+
+os.environ.update(IN_SPHINX="1")
+
+CONF_PY = Path(__file__)
+HERE = CONF_PY.parent
+ROOT = HERE.parent
+RTD = json.loads(os.environ.get("READTHEDOCS", "False").lower())
+
+# tasks that won't have been run prior to building the docs on RTD
+RTD_PRE_TASKS = ["build", "docs:typedoc:mystify", "docs:app:pack"]
+
+RTD_POST_TASKS = ["docs:post:schema", "docs:post:images"]
+
+# metadata
+author = 'Vassil Vassilev'
 project = 'CppInterOp'
 copyright = '2023, Vassil Vassilev'
-author = 'Vassil Vassilev'
 release = 'Dev'
 
-# -- General configuration ---------------------------------------------------
-# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
-
+# sphinx config
 extensions = []
 
-templates_path = ['_templates']
+autosectionlabel_prefix_document = True
+myst_heading_anchors = 3
+suppress_warnings = ["autosectionlabel.*"]
+
+# files
+templates_path = ["_templates"]
+# rely on the order of these to patch json, labextensions correctly
+html_static_path = [
+    # docs stuff
+    "_static",
+    # as-built assets for testing "hot" downstreams against a PR without rebuilding
+    "../dist",
+    # as-built application, extensions, contents, and patched jupyter-lite.json
+    "../build/docs-app",
+]
 exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
 
+html_css_files = [
+    "doxygen.css",
+]
 
-
-# -- Options for HTML output -------------------------------------------------
-# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
-
+# theme
 html_theme = 'alabaster'
-
 html_theme_options = {
     "github_user": "compiler-research",
     "github_repo": "CppInterOp",
@@ -33,25 +71,48 @@
     "fixed_sidebar": True,
 }
 
-highlight_language = "C++"
+html_context = {
+    "github_user": "compiler-research",
+    "github_repo": "CppInterOp",
+    "github_version": "main",
+    "doc_path": "docs",
+}
 
-todo_include_todos = True
 
-mathjax_path = "https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"
+def do_tasks(label, tasks):
+    """Run some doit tasks before/after the build"""
+    task_rcs = []
 
-# Add latex physics package
-mathjax3_config = {
-    "loader": {"load": ["[tex]/physics"]},
-    "tex": {"packages": {"[+]": ["physics"]}},
-}
+    for task in tasks:
+        print(f"[CppInterOp-docs] running {label} {task}", flush=True)
+        rc = subprocess.call(["doit", "-n4", task], cwd=str(ROOT))
 
-import os
-CPPINTEROP_ROOT = os.path.abspath('..')
-html_extra_path = [CPPINTEROP_ROOT + '/build/docs/']
+        if rc != 0:
+            rc = subprocess.call(["doit", task], cwd=str(ROOT))
 
-import subprocess
-command = 'mkdir {0}/build; cd {0}/build; cmake ../ -DClang_DIR=/usr/lib/llvm-13/build/lib/cmake/clang\
-         -DLLVM_DIR=/usr/lib/llvm-13/build/lib/cmake/llvm -DCPPINTEROP_ENABLE_DOXYGEN=ON\
-         -DCPPINTEROP_INCLUDE_DOCS=ON'.format(CPPINTEROP_ROOT)
-subprocess.call(command, shell=True)
-subprocess.call('doxygen {0}/build/docs/doxygen.cfg'.format(CPPINTEROP_ROOT), shell=True)
\ No newline at end of file
+        print(f"[CppInterOp-docs] ... ran {label} {task}: returned {rc}", flush=True)
+        task_rcs += [rc]
+
+    if max(task_rcs) > 0:
+        raise Exception("[CppInterOp-docs] ... FAIL, see log above")
+
+    print(f"[CppInterOp-docs] ... {label.upper()} OK", flush=True)
+
+
+def before_rtd_build(app: Sphinx, error):
+    """ensure doit docs:sphinx precursors have been met on RTD"""
+    print("[CppInterOp-docs] Staging files changed by RTD...", flush=True)
+    subprocess.call(["git", "add", "."], cwd=str(ROOT))
+    do_tasks("post", RTD_PRE_TASKS)
+
+
+def after_build(app: Sphinx, error):
+    """sphinx-jsonschema makes duplicate ids. clean them"""
+    os.environ.update(JLITE_DOCS_OUT=app.builder.outdir)  #
+    do_tasks("post", RTD_POST_TASKS)
+
+
+def setup(app):
+    app.connect("build-finished", after_build)
+    if RTD:
+        app.connect("config-inited", before_rtd_build)
\ No newline at end of file

From 35626329756a1b62cea43428543b3e40e409df15 Mon Sep 17 00:00:00 2001
From: mcbarton <150042563+mcbarton@users.noreply.github.com>
Date: Fri, 6 Dec 2024 19:44:12 +0000
Subject: [PATCH 2/9] Update rtd-preview.yml

---
 .github/workflows/rtd-preview.yml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/rtd-preview.yml b/.github/workflows/rtd-preview.yml
index f46f48c09..76abeace6 100644
--- a/.github/workflows/rtd-preview.yml
+++ b/.github/workflows/rtd-preview.yml
@@ -20,5 +20,5 @@ jobs:
               issue_number: context.issue.number,
               owner: context.repo.owner,
               repo: context.repo.repo,
-              body: `https://jupyterlite--${PR_NUMBER}.org.readthedocs.build/en/${PR_NUMBER}/_static/lab/index.html :point_left: Try it on ReadTheDocs`
-            })
\ No newline at end of file
+              body: `https://CppInterOp--${PR_NUMBER}.org.readthedocs.build/en/${PR_NUMBER}/_static/lab/index.html :point_left: Try it on ReadTheDocs`
+            })

From fc24e97da5218a3e0efa6eb06ca65c7661833baa Mon Sep 17 00:00:00 2001
From: mcbarton <150042563+mcbarton@users.noreply.github.com>
Date: Fri, 6 Dec 2024 19:48:08 +0000
Subject: [PATCH 3/9] Update rtd-preview.yml

---
 .github/workflows/rtd-preview.yml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/rtd-preview.yml b/.github/workflows/rtd-preview.yml
index 76abeace6..166e8a089 100644
--- a/.github/workflows/rtd-preview.yml
+++ b/.github/workflows/rtd-preview.yml
@@ -1,7 +1,7 @@
 name: RTD Preview
 on:
-  pull_request_target:
-    types: [opened]
+  pull_request:
+    branches: [main]
 
 permissions:
   pull-requests: write

From 3582c38667090e0b9427581eae1234db494bc260 Mon Sep 17 00:00:00 2001
From: mcbarton <150042563+mcbarton@users.noreply.github.com>
Date: Fri, 6 Dec 2024 19:48:49 +0000
Subject: [PATCH 4/9] Update rtd-preview.yml

---
 .github/workflows/rtd-preview.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/rtd-preview.yml b/.github/workflows/rtd-preview.yml
index 166e8a089..d3ba5ec1c 100644
--- a/.github/workflows/rtd-preview.yml
+++ b/.github/workflows/rtd-preview.yml
@@ -7,7 +7,7 @@ permissions:
   pull-requests: write
 
 jobs:
-  binder:
+  rtd-preview:
     runs-on: ubuntu-latest
     steps:
       - name: Comment on the PR with the RTD preview

From db799ff62dc55f1f23d10eb7085adc054e5fb394 Mon Sep 17 00:00:00 2001
From: mcbarton <150042563+mcbarton@users.noreply.github.com>
Date: Fri, 6 Dec 2024 19:50:57 +0000
Subject: [PATCH 5/9] Update rtd-preview.yml

---
 .github/workflows/rtd-preview.yml | 5 +----
 1 file changed, 1 insertion(+), 4 deletions(-)

diff --git a/.github/workflows/rtd-preview.yml b/.github/workflows/rtd-preview.yml
index d3ba5ec1c..b7836077c 100644
--- a/.github/workflows/rtd-preview.yml
+++ b/.github/workflows/rtd-preview.yml
@@ -2,10 +2,7 @@ name: RTD Preview
 on:
   pull_request:
     branches: [main]
-
-permissions:
-  pull-requests: write
-
+    
 jobs:
   rtd-preview:
     runs-on: ubuntu-latest

From 3de1eb3adc2516f02d1b0669da8f5daf6b8942e2 Mon Sep 17 00:00:00 2001
From: mcbarton <150042563+mcbarton@users.noreply.github.com>
Date: Fri, 6 Dec 2024 19:54:12 +0000
Subject: [PATCH 6/9] Update rtd-preview.yml

---
 .github/workflows/rtd-preview.yml | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/.github/workflows/rtd-preview.yml b/.github/workflows/rtd-preview.yml
index b7836077c..1217fe4c2 100644
--- a/.github/workflows/rtd-preview.yml
+++ b/.github/workflows/rtd-preview.yml
@@ -2,6 +2,14 @@ name: RTD Preview
 on:
   pull_request:
     branches: [main]
+
+permissions:
+  checks: write
+  pull-requests: write
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
     
 jobs:
   rtd-preview:

From 5dba02ab3f21ac54b5621a6f6774237b27b238ad Mon Sep 17 00:00:00 2001
From: mcbarton <150042563+mcbarton@users.noreply.github.com>
Date: Fri, 6 Dec 2024 20:23:34 +0000
Subject: [PATCH 7/9] Try fix

---
 docs/conf.py | 10 ----------
 1 file changed, 10 deletions(-)

diff --git a/docs/conf.py b/docs/conf.py
index 08fd489a9..699dbe7fc 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -47,15 +47,6 @@
 
 # files
 templates_path = ["_templates"]
-# rely on the order of these to patch json, labextensions correctly
-html_static_path = [
-    # docs stuff
-    "_static",
-    # as-built assets for testing "hot" downstreams against a PR without rebuilding
-    "../dist",
-    # as-built application, extensions, contents, and patched jupyter-lite.json
-    "../build/docs-app",
-]
 exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
 
 html_css_files = [
@@ -108,7 +99,6 @@ def before_rtd_build(app: Sphinx, error):
 
 def after_build(app: Sphinx, error):
     """sphinx-jsonschema makes duplicate ids. clean them"""
-    os.environ.update(JLITE_DOCS_OUT=app.builder.outdir)  #
     do_tasks("post", RTD_POST_TASKS)
 
 

From 347381ba6a02cba7d391d3c8a359929560985cbe Mon Sep 17 00:00:00 2001
From: mcbarton <150042563+mcbarton@users.noreply.github.com>
Date: Fri, 6 Dec 2024 20:44:02 +0000
Subject: [PATCH 8/9] Update conf.py

---
 docs/conf.py | 6 ++----
 1 file changed, 2 insertions(+), 4 deletions(-)

diff --git a/docs/conf.py b/docs/conf.py
index 699dbe7fc..af0d34764 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -30,8 +30,6 @@
 # tasks that won't have been run prior to building the docs on RTD
 RTD_PRE_TASKS = ["build", "docs:typedoc:mystify", "docs:app:pack"]
 
-RTD_POST_TASKS = ["docs:post:schema", "docs:post:images"]
-
 # metadata
 author = 'Vassil Vassilev'
 project = 'CppInterOp'
@@ -99,10 +97,10 @@ def before_rtd_build(app: Sphinx, error):
 
 def after_build(app: Sphinx, error):
     """sphinx-jsonschema makes duplicate ids. clean them"""
-    do_tasks("post", RTD_POST_TASKS)
+    os.environ.update(JLITE_DOCS_OUT=app.builder.outdir) 
 
 
 def setup(app):
     app.connect("build-finished", after_build)
     if RTD:
-        app.connect("config-inited", before_rtd_build)
\ No newline at end of file
+        app.connect("config-inited", before_rtd_build)

From f50e778ec9e0522f79068212fc7ffd8fb3dff38b Mon Sep 17 00:00:00 2001
From: mcbarton <150042563+mcbarton@users.noreply.github.com>
Date: Fri, 6 Dec 2024 20:45:07 +0000
Subject: [PATCH 9/9] Update rtd-preview.yml

---
 .github/workflows/rtd-preview.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/rtd-preview.yml b/.github/workflows/rtd-preview.yml
index 1217fe4c2..7d3b131c3 100644
--- a/.github/workflows/rtd-preview.yml
+++ b/.github/workflows/rtd-preview.yml
@@ -13,7 +13,7 @@ concurrency:
     
 jobs:
   rtd-preview:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-22.04
     steps:
       - name: Comment on the PR with the RTD preview
         uses: actions/github-script@v7