Update docs tooling

[greggyb]

3 major things in this PR, which can be split out if necessary:

1. Main build script: local tool and faster incremental build option
2. Link checker
3. C# script validator

Full docs of the new scripts can be found in build_scripts/README.md in this PR.

Main build script

Added one piece of plumbing and one new option

Resolve and use repo-local docfx instead of global

Add infrastructure to check for a global docfx on PATH or look for a repo-local installation that would be run as dotnet docfx. This resolves once and then uses the resolved invocation. This avoids requiring people to pollute their global PATH variable just to work on docs, or to use multiple versions of docfx in other repos.

Resolution is automatic and global docfx still works.

Faster incremental build

Add --skip-api option to allow skipping regeneration of the API docs, saving 5+s on every build. This is useful for iterative work with a locally served site.

Add --permissive option to not hard-fail on build warnings from docfx. This allows a file watcher to rebuild on every file change in the repo without blowing up. Again, this is useful for iterative work where one edit might yield a broken link that is intended to be fixed before commit.

Added defensive code around options to ensure that these don't accidentally get used in a full or CI build.

Link checker

Add build_scripts/check_links.py. This script walks the built _site directory to find all links in generated docs. It resolves every link, looking for failures:

• local doc resolution
• network issues
• HTTP failure stati
• missing #anchor fragments
• missing text fragments #:~:text=example
• special handling to check legacy root paths against live docs site to capture redirects

Dedupes URLs and uses a rudimentary scheduler to efficiently and politely fetch all URLs.

Report includes per-doc issues, a list of all URLs that fail to resolve, and optional per-domain statistics.

C# script checker

Add build_scripts/te_script_runner.py and build_scripts/csharp_doctest.py. The former wraps up te CLI for convenient execution of multiple scripts and is usable standalone or as a module in other Python scripts. The latter reads a small annotation grammar on C# fenced code blocks in markdown sources.

Annotations can be seen in code blocks in Semantic Bridge docs in this PR.

The script checker can validate its own annotation grammar in markdown files, compile code blocks to identify API drift, run code blocks to validate no runtime errors, and run codeblocks with output (to compare or update the in-doc output).

[Copilot]

Pull request overview

This PR updates the documentation toolchain by enhancing the main docs build script and adding two new validation tools (a built-site link checker and a C# fenced-code doctest runner) along with fixtures and documentation for running them.

Changes:

• Enhanced build-docs.py to resolve a repo-local DocFX invocation and added local-iteration flags (--skip-api, --permissive).
• Added build_scripts/check_links.py to validate href/src targets in the generated _site (including fragments/text-fragments and live-site redirect handling).
• Added C# snippet execution/validation tooling via build_scripts/te_script_runner.py and build_scripts/csharp_doctest.py, plus fixtures and documentation.

Reviewed changes

Copilot reviewed 18 out of 18 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
build-docs.py	Adds DocFX invocation resolution and local-iteration build flags/guards.
build_scripts/check_links.py	New built-site link checker with crawling, scheduling, and reporting.
build_scripts/te_script_runner.py	New TE CLI wrapper for running/compiling ordered C# snippets and summarizing JSON output.
build_scripts/csharp_doctest.py	New markdown C# fence parser/validator and runner for {compile} / {run ...} doctests.
build_scripts/README.md	Documents how to use the new scripts and fixtures.
build_scripts/test-fixtures/te-runtime-error.json	Fixture for te_script_runner.py summarize (runtime-error schema).
build_scripts/test-fixtures/te-run-ok.json	Fixture for te_script_runner.py summarize (successful run schema).
build_scripts/test-fixtures/te-dryrun-ok.json	Fixture for te_script_runner.py summarize (successful dry-run schema).
build_scripts/test-fixtures/te-dryrun-fail.json	Fixture for te_script_runner.py summarize (dry-run failure schema).
build_scripts/test-fixtures/te-compile-error.json	Fixture for te_script_runner.py summarize (compile-error schema).
build_scripts/test-fixtures/err-unknown-annotation.md	Fixture for doctest annotation validation failure.
build_scripts/test-fixtures/err-unknown-after.md	Fixture for doctest after= reference validation failure.
build_scripts/test-fixtures/err-run-on-yaml.md	Fixture for invalid annotation on non-csharp fence.
build_scripts/test-fixtures/err-no-output-fence.md	Fixture for missing required output fence after output=true.
build_scripts/test-fixtures/err-missing-option.md	Fixture for missing required {run ...} option(s).
build_scripts/test-fixtures/doc-valid.md	Fixture representing a fully valid annotated document.
build_scripts/test-fixtures/doc-mismatch.md	Fixture representing output mismatch for compare/update behavior.
build_scripts/test-fixtures/doc-compile-drift.md	Fixture representing compile drift in a {run ...} block.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[github-actions]

Azure Static Web Apps: Your stage site is ready! Visit it here: https://delightful-mud-081affe03-360.westeurope.azurestaticapps.net

[github-actions]

Azure Static Web Apps: Your stage site is ready! Visit it here: https://delightful-mud-081affe03-360.westeurope.azurestaticapps.net

[github-actions]

Azure Static Web Apps: Your stage site is ready! Visit it here: https://delightful-mud-081affe03-360.westeurope.azurestaticapps.net