refactor: Migrate remaining ex_dir= call sites to add_example(example_name=)#2329
Merged
Conversation
Adds an example_name= parameter to @add_example() that looks up the example in the nearest api-examples/ directory (same walk-up mechanism as the no-argument form), and migrates all 37 ex_dir= call sites that pointed inside an api-examples/ tree. Also fixes nine call sites in shiny/session/_session.py and shiny/bookmark/_bookmark.py that passed the example name positionally, where it was silently consumed as app_file= and the example was omitted from the generated docs with only a build warning. The example_name= parameter matches the semantics of the one proposed in #2278 so the two changes merge cleanly. Fixes #2328
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
1 participant
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 #2328
Summary
Adds an
example_name=parameter to the internal@add_example()decorator (shiny/_docstring.py) and migrates all 37ex_dir=call sites that pointed inside anapi-examples/tree.example_name="foo"finds the nearestapi-examples/directory by walking up from the decorated object's source file (the same mechanism as the no-argument form) and looks up thefoosubdirectory, replacing fragile hardcoded relative paths likeex_dir="../../api-examples/foo". A missingexample_namedirectory raisesFileNotFoundErrorduring docs builds instead of resolving to a wrong path.The parameter is implemented with the same signature and semantics as the one proposed in #2278 (
*-keyword-only args, mutual exclusivity withex_dir=), so the two changes should merge cleanly whichever lands first. This PR intentionally does not include #2278's warn-to-raise behavior change for missing example app files, nor its new example apps.This also fixes nine call sites in
shiny/session/_session.pyandshiny/bookmark/_bookmark.pythat passed the example name positionally (e.g.@add_example("session_close")), where it was silently consumed asapp_file=; those examples were being dropped from the generated docs with only a::warningin the build log. Withadd_example()now keyword-only, such mistakes are aTypeErrorat import time (whenSHINY_ADD_EXAMPLES=true).ex_dir=is retained (its docstring now says to preferexample_name=) for the case where an example lives outside the nearestapi-examples/tree; no call sites currently need it.Verification
SHINY_ADD_EXAMPLES=true SHINY_MODE=core python -c "import shiny, shiny.express"and the same withSHINY_MODE=expressboth succeed. Comparing::warningoutput againstmain: no new warnings, and the nine warnings from the broken positional call sites are gone (their examples now resolve). The two remainingbookmark_callbacksexpress warnings are pre-existing (noapp-express.pyyet; docs: fail on missing API examples #2278 adds one).make docs-quartodocbuilds cleanly (exit 0).grep -rn 'ex_dir=' shiny/matches only the parameter definition in_docstring.py.main.