docs: make executed examples deterministic and figures accessible - #1503
Draft
s3alfisc wants to merge 2 commits into
Draft
docs: make executed examples deterministic and figures accessible#1503s3alfisc wants to merge 2 commits into
s3alfisc wants to merge 2 commits into
Conversation
Documentation pages that Quarto executes produced different numbers on every render. `poisson-glm.qmd` derived fixed effects from `hash()` of string labels, which varies with Python's per-process hash seed. The changelog drew decomposition weights without a generator, ran `decompose()`, `confint(joint=True)` and `ccv()` without seeds, and printed wall-clock benchmark timings into the page. Seed the random paths, index the fixed effects by position, and hide the benchmark cell's timing output while keeping the `etable` comparison that backs the performance claim. `replicating-the-effect.qmd` now copies the filtered frame so the page no longer renders a `SettingWithCopyWarning`, and the `IV_Diag` docstring example carries an explicit cell label so its generated reference page keeps a stable anchor. Freeze results are regenerated for the three executed pages.
Most figures shipped with no description at all: the benchmark plots in `difficult-fixed-effects.md` sat in raw `<p align="center"><img>` wrappers with a separate italic caption underneath, and the logos and the quantreg benchmark used empty `![]()`. Only `bench_readme.png` carried an `alt` attribute. Where a figure wants a visible caption, use Markdown alt text, which Quarto renders as the caption: `difficult-fixed-effects.md` and the quantreg benchmark now fold their italic caption paragraphs into that position, so each figure has exactly one caption, and width and alignment go through Quarto's figure handling instead of inline HTML. Where a figure wants no caption - the logos, the README benchmark, and the changelog benchmark that already has an italic caption - use `fig-alt`, which sets a real `alt` attribute and adds nothing visible. The README keeps its raw `<img>` for the funder badge, which GitHub sizes, and gains an `alt` attribute there. Freeze results are regenerated for the two executed pages.
Codecov Report✅ All modified and coverable lines are covered by tests.
Flags with carried forward coverage won't be shown. Click here to find out more.
... and 10 files with indirect coverage changes 🚀 New features to boost your workflow:
|
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.
Summary
Executed documentation pages now render the same numbers on every build, and every figure carries a text description.
poisson-glm.qmdderived fixed effects fromhash()of string labels, which changes with Python's per-process hash seed; the changelog randecompose(),confint(joint=True), andccv()unseeded and printed wall-clock timings into the page; several figures were raw<img>wrappers or empty![]()links. Markdown alt text is used where a visible caption is wanted,fig-altwhere it is not. Independent of the other documentation branches.docs/_freeze/**is regenerated for the re-rendered pages; several were stale (one still reported pyfixest 0.40.1), so the results also absorb drift already onmaster.Verification
git diff --check;docs-build; individual renders of the six touched pages plus theFeivreference page, inspected for images, tables, and errors;ruff-check/ruff-formatonfeiv_.py;pytest tests/test_iv.py(60 passed, 6 skipped: RivDiagabsent locally). Seeded examples verified byte-identical across processes. Fulldocs-renderdeferred to CI.