Add docs PR preview

Author: mcbarton

.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`
+            })

.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

docs/conf.py

@@ -1,57 +1,118 @@
-# 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",
     "github_banner": True,
     "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)
+        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)