diff --git a/.github/workflows/rtd-preview.yml b/.github/workflows/rtd-preview.yml
new file mode 100644
index 000000000..7d3b131c3
--- /dev/null
+++ b/.github/workflows/rtd-preview.yml
@@ -0,0 +1,29 @@
+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:
+    runs-on: ubuntu-22.04
+    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://CppInterOp--${PR_NUMBER}.org.readthedocs.build/en/${PR_NUMBER}/_static/lab/index.html :point_left: Try it on ReadTheDocs`
+            })
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..af0d34764 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -1,31 +1,58 @@
-# 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"]
+
+# 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']
-exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
-
+autosectionlabel_prefix_document = True
+myst_heading_anchors = 3
+suppress_warnings = ["autosectionlabel.*"]
 
+# files
+templates_path = ["_templates"]
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
 
-# -- Options for HTML output -------------------------------------------------
-# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+html_css_files = [
+    "doxygen.css",
+]
 
+# theme
 html_theme = 'alabaster'
-
 html_theme_options = {
     "github_user": "compiler-research",
     "github_repo": "CppInterOp",
@@ -33,25 +60,47 @@
     "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) 
+
+
+def setup(app):
+    app.connect("build-finished", after_build)
+    if RTD:
+        app.connect("config-inited", before_rtd_build)