Repository navigation
refactor: run the build from a table of steps - #485
Merged
Merged
Conversation
📚 Preview this PR's docs locallyFetch the just-built site and open it in your browser: # this exact build
great-docs preview --run 41082660858
# or always the latest build for this PR
great-docs preview --pr 485Auth & tips
|
Represent build steps as rows with an action and logging policy. Add a runner that numbers listed rows, reports results and skip reasons, sends `print()` output to build log detail lines, and runs project code from the build directory. Report recoverable step failures as warnings. Report fatal step failures and print the footer before raising `BuildError`. The build does not use the runner yet.
End the log after the failure line, details and footer when Quarto fails to render the site or every version of a versioned site fails. Omit the subsequent "Generate SEO files" skip entry so render failures end the log in the same way as other fatal failures.
Describe the build as rows with an action, logging policy and working directory. Derive step numbers and the total from the listed rows instead of a fixed count. Each action returns a result line or skip reason. Preserve the twenty numbered steps, result lines, warnings and footer. Continue to run steps that import or execute project code from the build directory and send `print()` output to build log detail lines. Use the shared Quarto configuration editor when retrying API reference generation with static analysis.
Limit the exceptions that build steps convert to warnings. The CLI and MCP server references and the API snapshot still warn and continue on `ImportError`, `SyntaxError`, `AttributeError`, `RuntimeError`, `OSError` and griffe errors from importing or running project code. The Go and Rust CLI references catch `OSError`. The API reference also catches configured names it cannot find. SEO file generation still warns on `OSError`. Stop the build on failures when generating the changelog, processing the user guide, custom sections, custom pages, page tags or status badges, or copying assets. Report the step as failed and raise `BuildError` when a user guide, custom section or custom page path escapes the build directory, or the assets step finds no header include file. Propagate all other exceptions from these steps unchanged. Also propagate errors in great-docs itself outside steps that handle project code failures, such as `AttributeError`.
has2k1
force-pushed
the
refactor/step-table
branch
from
October 30, 2026 15:38
a6b2438 to
9f9143b
Compare
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.
The build now runs from one ordered table of steps instead of a long method that numbered each step by hand. Step numbers and the total came from a hard-coded count of twenty, and each step repeated its own logging, output capture, working-directory change and error handling. A row now declares these, so adding, removing or reordering a step no longer means renumbering the rest. The step log is unchanged.
Two things change for site authors whose build fails. A failed render now ends the log at the failure, without the "Generate SEO files, Skipped" line that followed it. Failures in the changelog, user guide, custom sections, custom pages, tags, status badges and assets steps now stop the build instead of being shown as warnings over an incomplete site. When the failure is a problem in the project, such as a path that leaves the build directory or a missing header include, the log names the failing step and gives the reason. Steps that import or run the project's code still warn when that code fails.