docs: fail on missing API examples#2278
Merged
schloerke merged 10 commits intoJul 6, 2026
Merged
Conversation
Collaborator
|
Thank you for the PR! I'll review more closely at the start of next week |
Contributor
There was a problem hiding this comment.
Pull request overview
This PR tightens the documentation build pipeline by turning missing @add_example() references into hard failures during quartodoc generation, and it fills/adjusts several API example linkages to eliminate existing missing-example warnings.
Changes:
- Make
@add_example()raise an error (during docs builds) when the expected example file can’t be found, instead of emitting a GitHub Actions warning. - Fix/standardize example directory references for Session and Bookmark APIs, and mark selected APIs as Core-only for examples where needed.
- Add missing Shiny Express example apps for several UI helpers/layout patterns.
Reviewed changes
Copilot reviewed 12 out of 12 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
| shiny/_docstring.py | Convert missing-example handling from a workflow warning to a hard failure when SHINY_ADD_EXAMPLES=true. |
| shiny/ui/_input_update.py | Explicitly mark update_navs() as having no example (and avoid example enforcement for this deprecated API). |
| shiny/session/_session.py | Point session method examples at the correct shiny/api-examples/* directories via ex_dir=.... |
| shiny/bookmark/_bookmark.py | Fix bookmark example directory references and mark callback examples as Core-only where no Express example exists. |
| shiny/bookmark/_restore_state.py | Mark restore_input() example as Core-only and ensure no_example is available. |
| shiny/render/transformer/_transformer.py | Mark output_transformer() example as Core-only for Express builds. |
| shiny/api-examples/card_body/app-express.py | Add an Express example for card_body. |
| shiny/api-examples/download_link/app-express.py | Add an Express example for download_link. |
| shiny/api-examples/row/app-express.py | Add an Express example for row/column layout. |
| shiny/api-examples/showcase_bottom/app-express.py | Add an Express example for showcase_bottom(). |
| shiny/api-examples/showcase_left_center/app-express.py | Add an Express example for showcase_left_center(). |
| shiny/api-examples/showcase_top_right/app-express.py | Add an Express example for showcase_top_right(). |
… output_transformer
Removes the @no_example("express") markers now that each API has an
app-express.py example. render.text and render.plot already had Express
examples, so their markers were stale.
Keeps all of add_example()'s failure paths as FileNotFoundError subclasses and preserves the express/core exception subtype. The decorated function's name is attached to the exception so the docs build failure points at the API missing its example. Also documents the Raises behavior in the docstring.
… keyword-only example_name looks up the named directory in the nearest api-examples/ directory (walking parent directories), removing the need for fragile relative ex_dir paths when the example directory does not match the decorated object's __name__. ex_dir and example_name are mutually exclusive. Migrates the call sites introduced in this PR.
schloerke
reviewed
Jul 6, 2026
| @add_example() | ||
| @no_example() | ||
| @doc_format(note=_note) | ||
| def update_navs( |
Collaborator
There was a problem hiding this comment.
Deprecated function. Correct code change above
Collaborator
|
Thank you, @EltonChang1 ! ✍️ |
- Theme's example directory is lowercase 'theme', which only resolved on
case-insensitive filesystems; reference it explicitly via example_name.
- Rewrite card_body Express example with context-manager syntax
(express card_body() takes no positional children).
- Remove Express examples for core-only APIs (row/column, download_link,
showcase_*) and mark them @no_example("express") instead, matching
shiny.express.ui's _known_missing design.
schloerke
added a commit
that referenced
this pull request
Jul 6, 2026
Resolves conflicts with #2278, which merged first and added the same example_name= parameter to @add_example(): - shiny/_docstring.py: keep main's version plus the docstring note to prefer example_name= over ex_dir=. - shiny/render/_render.py: keep main's removal of @no_example("express") on render.text and render.plot (express examples now exist), with the example_name= spelling. - shiny/ui/_bootstrap.py: keep main's added @no_example("express") on column(), with the example_name= spelling.
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.
Closes #2164
Summary
Validation
Limitations
AI disclosure
This draft PR was prepared with assistance from OpenAI Codex/ChatGPT. Codex investigated issue #2164, implemented the source/example changes, ran the validation commands listed above, and drafted this PR text.