docs: write example reports under output/ so they stay untracked - #981
Merged
Merged
Conversation
The quickstart examples wrote report.html into the working directory, so anyone following the README ends up with a stray untracked file at the repo root. `report.html` was added to .gitignore once for exactly this reason (909bb71), but .gitignore is rhiza-managed and the v1.3.0 sync (7152802) removed the line again. Point the examples at output/ instead, which the template .gitignore already ignores for docstring-example artefacts, and which `_reports/_portfolio.py` and `book/shots/generate.py` already use. No managed file is touched, so a sync cannot undo it. For the Portfolio route this collapses to `to_html(path=...)`, which mkdirs the parent itself; `data.reports.full()` only returns a str, so the gallery example keeps an explicit write and gains the mkdir. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
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.
Why
Following the README quickstart leaves a stray untracked
report.htmlat the repo root. That was noticed before and fixed by adding the file to.gitignorein 909bb71 — but.gitignoreis rhiza-managed (.rhiza/template.lock:31), and the v1.3.0 sync (7152802) deleted the line again. Any local.gitignorefix has the same fate.What
Point the doc examples at
output/instead. The template.gitignorealready ignores it (line 8, "HTML outputs from docstring examples"), andsrc/jquantstats/_reports/_portfolio.py:201andbook/shots/generate.py:209already write there. No template-owned file is touched, so a sync cannot undo this.README.md:331pf.report.to_html(path="output/report.html")docs/getting_started.md:196docs/gallery.md:232mkdir(parents=True, exist_ok=True)docs/MIGRATION.md:355docs/index.mdis--8<-- "README.md", so the landing page follows automatically.For the Portfolio route
to_html(path=...)creates the parent directory itself (_portfolio.py:331), so nomkdiris needed.data.reports.full()only returns astr, which is why the gallery example keeps a manual write.Verified
Ran the rewritten README example in an empty directory:
output/was created and a 101 KB report written. Docs-only otherwise — no doc code blocks are executed by the suite (no doctest/mktestdocs/markdown-exec configured).Not in scope
docs/paper/jquantstats.tex:785writesstrategy_report.htmlto the cwd. It is a published paper, so I left it alone — say the word if you want it aligned.🤖 Generated with Claude Code