Repository navigation
docs: add interactive Python runtime architecture GitHub Pages - #1949
Merged
Merged
Conversation
Add a code-grounded, multi-repository interactive Architecture Atlas for the Azure Functions Python runtime and wire up automated GitHub Pages builds: - Extract live Python AST, Rust (R2P2), and FunctionRpc.proto symbols across python-worker, python-library, python-extensions, and language-worker-protobuf (eng/docs/extract_arch.py + eng/docs/phases_spec.py). - Model all 3 worker generations (<= 3.12 monolith, 3.13-3.14 proxy_worker + runtimes split, 3.15+ R2P2 Rust/PyO3 worker) across all 7 lifecycle phases (Init, Specialization, Metadata, Functions Load, Invocation, Worker Status, and Worker Logs). - Render algorithmic compound swimlane topologies, multi-actor sequence flows, cross-era phase comparisons, and deterministic Mermaid exports (docs/site/). - Add unit tests (eng/docs/tests/test_extract_arch.py) and GitHub Pages CI/CD (.github/workflows/architecture-pages.yml). Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Varad Meru (vrdmr)
requested review from
Gavin Aguiar (gavin-aguiar) and
hallvictoria
as code owners
November 15, 2026 23:59
Skip running the full worker build, emulator, and integration matrices when changes only touch docs/*, eng/docs/*, or .github/workflows/architecture-pages.yml. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
There was a problem hiding this comment.
🟡 Changes recommended
Unresolved defects include a navigation toggle that hides main content, accumulating topology event listeners, and component controls that keyboard users cannot activate.
5 open issues
Topology nodes and boundary controls are inaccessible by keyboard · New Zoom controls use inconsistent bounds and can reverse zoom direction · New Topology rerenders leak global mouse event listeners · New Hidden sidebar leaves workspace in a zero-width grid column · New Method symbol lookups use hard-coded line-number fallbacks · New
What changed in this PR
Adds an interactive Architecture Atlas for the Azure Functions Python runtime, connecting four repositories and documenting three worker generations without changing runtime behavior.
Changes:
- Adds topology diagrams, lifecycle sequences, cross-generation comparisons, and Mermaid exports.
- Introduces a Python/Rust/Proto extractor, lifecycle specifications, and extractor tests.
- Adds GitHub Pages automation and excludes documentation-only changes from worker CI matrices.
| File | Description |
|---|---|
eng/docs/tests/test_extract_arch.py |
Tests graph structure, extraction, and validation. |
eng/docs/phases_spec.py |
Defines seven lifecycle phases for each worker generation. |
eng/docs/extract_arch.py |
Generates architecture data, source links, and Mermaid exports. |
eng/ci/public-build.yml |
Excludes documentation paths from build triggers. |
eng/ci/official-build.yml |
Excludes documentation paths from release-build triggers. |
eng/ci/integration-tests.yml |
Skips integration triggers for documentation-only changes. |
eng/ci/emulator-tests.yml |
Skips emulator triggers for documentation-only changes. |
docs/site/README.md |
Documents local preview and Pages setup. |
docs/site/index.html |
Loads the site and generated graph data. |
docs/site/assets/styles.css |
Styles the responsive workspace and diagrams. |
docs/site/assets/layoutEngine.js |
Computes graph layouts and edge routes. |
docs/site/assets/app.js |
Implements navigation, diagrams, inspectors, and exports. |
docs/site/.nojekyll |
Disables Jekyll processing for the static site. |
.gitignore |
Ignores generated data and sibling checkouts. |
.github/workflows/architecture-pages.yml |
Validates, builds, and deploys the Pages site. |
Review effort: Balanced
…rs, layout, and AST method anchors - Add keyboard focus, Enter/Space activation, ARIA labels, <button> boundary controls, and focus restoration across rerenders (app.js, styles.css). - Unify zoom bounds (ZOOM_MIN=0.12, ZOOM_MAX=1.8) across auto-fit, +/- buttons, and wheel handlers (app.js). - Dispose global window mousemove/mouseup listeners on rerender via AbortController (app.js). - Fix collapsed desktop sidebar grid template to 1fr so workspace expands instead of collapsing into a 0px column (styles.css). - Index class method line numbers without truncation before sym_line() lookup and add unit test coverage (extract_arch.py, test_extract_arch.py). Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
…f contract Add Azure/azure-functions-host as the 5th linked repository across the ecosystem topology and all 3 worker generations so the .NET Script Host runtime (WorkerChannel / ServerDuplexChannel) is cleanly distinguished from the shared FunctionRpc.proto wire contract. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
There was a problem hiding this comment.
🟡 Changes recommended
Unresolved defects leave sequence highlighting out of sync, prevent touch-only diagram panning, and omit multiline or lifetime-parameterized functions from extracted symbol maps.
3 open issues
5 resolved since last review
Method symbol lookups use hard-coded line-number fallbacks Hidden sidebar leaves workspace in a zero-width grid column Topology rerenders leak global mouse event listeners Zoom controls use inconsistent bounds and can reverse zoom direction Topology nodes and boundary controls are inaccessible by keyboard
Review effort: Balanced
…and parse multiline/generic Rust fns - Derive stepList and activeStep from seqSource so Ecosystem and All Edges sequence selections synchronize with Compound Topology (app.js). - Switch topology stage panning to Pointer Events with pointer capture, touch-action: none, and cancel/lostpointercapture cleanup (app.js, styles.css). - Support generic/lifetime parameters and multiline Rust function declarations in extract_rust_file() with regression tests for configure, typed_data_to_tuple, and worker_init_req_to_py (extract_arch.py, test_extract_arch.py). Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Restore sys.path via an autouse monkeypatch fixture so pytest-cov teardown on Python 3.14 does not fail with ModuleNotFoundError: No module named 'http'. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Gavin Aguiar (gavin-aguiar)
previously approved these changes
Nov 16, 2026
…arkdown + Mermaid Preserve all architecture documentation, component tables, and 7-phase lifecycle Mermaid diagrams directly in committed Markdown files under docs/architecture/ while embedding the interactive AST/PyO3 Architecture Explorer on MkDocs Material pages: - Add mkdocs.yml (Material theme, search, dark/light toggle, Mermaid fences, official Azure Functions logo) and eng/docs/requirements.txt. - Add committed Markdown guides (docs/index.md, docs/architecture/overview.md, ecosystem.md, python-312.md, python-313-314.md, python-315-r2p2.md, dependency-isolation.md, auto-sync-pipeline.md). - Add --sync-markdown and --check-markdown modes to eng/docs/extract_arch.py with unit test verification so bounded Mermaid/component blocks stay synced. - Mount embeddable interactive explorer (docs/assets/atlas-embed.js) with fullscreen mode alongside static Markdown content. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Varad Meru (vrdmr)
temporarily deployed
to
github-pages
November 16, 2026 18:05 — with
GitHub Pages
Inactive
…TED blocks - Remove navigation.tabs and add navigation.expand in mkdocs.yml so the left-hand navigation tree stays permanently visible across all pages. - Surround AUTO-GENERATED Markdown blocks with blank lines so pipe tables before <!-- END AUTO-GENERATED --> parse cleanly in all Markdown engines. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Varad Meru (vrdmr)
temporarily deployed
to
github-pages
November 16, 2026 18:16 — with
GitHub Pages
Inactive
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Varad Meru (vrdmr)
temporarily deployed
to
github-pages
November 16, 2026 18:26 — with
GitHub Pages
Inactive
Varad Meru (vrdmr)
temporarily deployed
to
github-pages
November 16, 2026 18:26 — with
GitHub Actions
Inactive
…line page
- Override MkDocs Material's .md-typeset svg { height: auto } rule on
.aa-stage > svg so the interactive Compound Topology fills 100% of the
stage instead of collapsing to the 150px intrinsic SVG height.
- Prevent 'GitHub ↗' badge text from wrapping mid-word in the inspector.
- Remove the Commit Auto-Sync Pipeline page from the Architecture nav.
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Varad Meru (vrdmr)
temporarily deployed
to
github-pages
November 16, 2026 21:05 — with
GitHub Actions
Inactive
Varad Meru (vrdmr)
temporarily deployed
to
github-pages
November 16, 2026 21:05 — with
GitHub Pages
Inactive
Varad Meru (vrdmr)
temporarily deployed
to
github-pages
November 16, 2026 21:07 — with
GitHub Actions
Inactive
…extensions below library - Replace 1D horizontal root-container chain with topological tier columns and orthogonal vertical intra-container stacking (2:1 - 3:1 aspect ratio). - Separate python-library and python-extensions containers across all views and stack python-extensions directly below python-library in the same tier column. - Move the component inspector below the topology stage so diagrams span the full page width, and switch static Mermaid topologies to flowchart TB. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Varad Meru (vrdmr)
temporarily deployed
to
github-pages
November 16, 2026 21:25 — with
GitHub Actions
Inactive
Varad Meru (vrdmr)
temporarily deployed
to
github-pages
November 16, 2026 21:25 — with
GitHub Pages
Inactive
…e cards Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Varad Meru (vrdmr)
temporarily deployed
to
github-pages
November 16, 2026 21:28 — with
GitHub Pages
Inactive
Varad Meru (vrdmr)
temporarily deployed
to
github-pages
November 16, 2026 21:28 — with
GitHub Actions
Inactive
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Varad Meru (vrdmr)
temporarily deployed
to
github-pages
November 16, 2026 22:33 — with
GitHub Actions
Inactive
Varad Meru (vrdmr)
temporarily deployed
to
github-pages
November 16, 2026 22:33 — with
GitHub Pages
Inactive
Varad Meru (vrdmr)
temporarily deployed
to
github-pages
November 16, 2026 22:35 — with
GitHub Actions
Inactive
Gavin Aguiar (gavin-aguiar)
approved these changes
Nov 16, 2026
Gavin Aguiar (gavin-aguiar)
enabled auto-merge (squash)
November 16, 2026 23:23
Gavin Aguiar (gavin-aguiar)
deleted the
vrdmr-docs-architecture-pages
branch
November 16, 2026 23:27
This branch was previously deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.

Description
Fixes # N/A
Adds an MkDocs Material engineering documentation site (
mkdocs.yml+ committed Markdown underdocs/architecture/) paired with an auto-extracted Interactive Architecture Explorer (eng/docs/+docs/assets/) for the Azure Functions Python runtime:docs/index.md,docs/architecture/*.md):mermaidsequence & compound topology diagrams committed directly in Git (readable in GitHub's repo viewer, PR diffs, and MkDocs search).<!-- BEGIN AUTO-GENERATED: ... -->sections kept in sync viapython3 eng/docs/extract_arch.py --sync-markdownand verified in CI (--check-markdown).docs/assets/atlas-embed.js):⛶ Expand), pan/zoom (mouse + touch Pointer Events), keyboard navigation, 7-phase lifecycle selector, hop-by-hop packet trace, 3-era phase comparison, and live Python AST / Rust / Protobuf symbol line anchors.Azure/azure-functions-host(.NET Script Host runtime),Azure/azure-functions-language-worker-protobuf(Host ↔ Worker wire contract),Azure/azure-functions-python-worker,Azure/azure-functions-python-library, andAzure/azure-functions-python-extensions.<= 3.12(workers/azure_functions_worker), Python3.13 - 3.14(workers/proxy_worker+runtimes/{v1,v2}), and Python3.15+(workers/r2p2Rusttonic/prost+PyO3+runtimes/{v1,v2}).Worker Init,Specialization(Consumption),Metadata & Indexing,Functions Load (V1),Invocation,Worker Status, andWorker Logs(RpcLog).workers/tests/unittest_proxy/test_dependency.py): Adds anautousepreserve_sys_pathfixture sosys.pathmutations do not breakpytest-covteardown (Path.as_uri()->import http.client) on Python 3.14.docs/*,eng/docs/*,mkdocs.yml, and.github/workflows/architecture-pages.ymlfrom full worker test matrices, and builds/deploys viamkdocs build --strictto GitHub Pages.Validation
python3 -m unittest discover -s eng/docs/tests -v— Passed (Ran 8 tests in 0.273s — OK)python3 eng/docs/extract_arch.py --check-markdown— Passed (verified all committed MarkdownAUTO-GENERATEDblocks match extracted 5-repo graph)mkdocs build --strict— Passed (Documentation built in 0.21 secondswith zero warnings)Pull Request Checklist
Host-Worker Contract
mkdocs.yml,docs/), read-only AST/Rust/Proto extractor (eng/docs/), unit-testsys.pathfixture cleanup, and CI path exclusions only; no runtime or gRPC wire behavior is modified.Worker Execution Logic
If yes, please answer the following:
Python Version Coverage
<= 3.12,3.13-3.14, and>= 3.15R2P2 architectures in docs without modifying worker execution code).Programming Model Compatibility (proxy_worker and r2p2)
runtimes/v1) and V2 (runtimes/v2) across all 7 lifecycle phases.