Update docs tooling#360
Open
greggyb wants to merge 14 commits into
Open
Conversation
- Error handling for workers so they can't hang - siginfo, sigquit, sigbreak (C-t, C-\, and C-break) give a status update while running - sigint (C-c) prints stats and exits cleanly
Contributor
There was a problem hiding this comment.
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.pyto resolve a repo-local DocFX invocation and added local-iteration flags (--skip-api,--permissive). - Added
build_scripts/check_links.pyto 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.pyandbuild_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.
|
Azure Static Web Apps: Your stage site is ready! Visit it here: https://delightful-mud-081affe03-360.westeurope.azurestaticapps.net |
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
|
Azure Static Web Apps: Your stage site is ready! Visit it here: https://delightful-mud-081affe03-360.westeurope.azurestaticapps.net |
|
Azure Static Web Apps: Your stage site is ready! Visit it here: https://delightful-mud-081affe03-360.westeurope.azurestaticapps.net |
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.
3 major things in this PR, which can be split out if necessary:
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
PATHor look for a repo-local installation that would be run asdotnet docfx. This resolves once and then uses the resolved invocation. This avoids requiring people to pollute their globalPATHvariable just to work on docs, or to use multiple versions of docfx in other repos.Resolution is automatic and global
docfxstill works.Faster incremental build
Add
--skip-apioption 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
--permissiveoption 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:#:~:text=exampleDedupes 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.pyandbuild_scripts/csharp_doctest.py. The former wraps upteCLI 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).