docs: every block that shows output now produces it - #35
Open
sotashimozono wants to merge 2 commits into
Open
Conversation
Measured: 33 fenced ```julia blocks across `docs/src`, of which **12 displayed output that had
been typed by hand**. Those 12 are the ones that can be wrong, and three of them were.
All 12 now execute — `@setup` fixtures plus `@repl`/`@example` — and the build fails if their
output stops matching. Typed-output blocks remaining: 0.
What executing them found:
* `@experimental "why" Base.sum(x::Int) = x` is documented as REFUSED. It is accepted: method
marks on another module's generic landed in #13, and the page was never revisited. The
refusal example is now one that is still refused (a bare `Sub.g`), rendered from the real
message, and the accepted-forms list gains the foreign-method case with the note that it is
reported by `contributed_methods` rather than by the name audit.
* `mark(Archeion, :ingest)` was shown without its `signature:` line, which the real display has.
* The `entered()` transcript carried a reason for not being executable — "Documenter evaluates
doctests in a sandbox whose module does not print as `Main`". Measured: an `@repl` block shows
`Main.MyModel.energy`, so the reason no longer holds. It is now `entered(MyModel)`, asked about
a module because the process-wide answer includes every fixture the documentation built.
Two blocks show what a documentation build genuinely gets rather than what a user would, and say
so: `record`'s timings are `missing` because a docs build does not load `Profile`, and
`coverage(...)` is `missing` because it has no `--code-coverage` counters. Both are the documented
contract, now demonstrated instead of described.
`record(; paths = false)` on the observing page: a captured path is the whole call stack, and in a
docs build that starts at `_start` and runs through `makedocs`.
1253 assertions, green; docs build clean.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
github-actions
Bot
added
the
documentation
Contributor
|
📚 Docs preview: https://codes.sota-shimozono.com/ExperimentalAPI.jl/previews/PR35/ (updates on each push to this PR) |
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
…y the macro
The walkthrough showed
value = ExperimentalAPI.@entered Ising.report(βs)
-1.8886
— the value, and nothing else. The report is the whole of what `@entered` is for.
Not the macro. `IOCapture`, which is what Documenter captures with, sees it:
captured output = "┌ @entered S.f(1.0) at cap.jl:8\n│ Main.S.f ×1 — r\n└ 0 of 1 …\n"
value = 2.0
Measured on a minimal Documenter site, with the control that settles it:
block value rendered
@entered S.f(1.0) 2.0 2.0
println("plain println"); 99 99 99 ← the println is lost too
println("plain println only") nothing plain println only
An `@example` renders the block's value when it has one and its captured output only when the
value is `nothing`. A plain `println` followed by a non-`nothing` value loses its line exactly the
same way, which is what says this is Documenter and not us.
So the walkthrough uses `@entered <io> expr` and prints the buffer — the form `observing.md`
already used for the same reason — and the page now says why, with the control, and adds that a
reader at a terminal writes the plain form. All three `@entered` blocks in the built docs now
carry their report.
1250 assertions, green.
Co-Authored-By: Claude Opus 5 <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.
Measured before touching anything: 33 fenced ```julia blocks across
docs/src, of which 12displayed output typed by hand. Those 12 are the ones that can be wrong — and three of them were.
All 12 now execute (
@setupfixtures plus@repl/@example), and the build fails if their outputstops matching.
```julia```@example/```@repl/```@setupWhat executing them found
@experimental "why" Base.sum(x::Int) = xis documented as refused. It is accepted. Methodmarks on another module's generic landed in #13 and this page was never revisited. The refusal
example is now one that is still refused — a bare
Sub.g— rendered from the real message:…and the accepted-forms list gains the foreign-method case, with the note that it is reported by
contributed_methodsrather than by the name audit.mark(Archeion, :ingest)was shown without itssignature:line, which the real display has.The
entered()transcript carried a reason for not being executable — "Documenter evaluatesdoctests in a sandbox whose module does not print as
Main". Measured: an@replblock rendersMain.MyModel.energy, so the reason no longer holds. It is nowentered(MyModel), asked about amodule because the process-wide answer includes every fixture the documentation built.
Two blocks now show what a docs build genuinely gets
…and say so, rather than showing what a user would get:
record's timings aremissing— a documentation build does not loadProfilecoverage(...)ismissing— it has no--code-coveragecountersBoth are the documented contract, demonstrated instead of described.
Also
record(; paths = false)on the observing page: a captured path is the whole call stack, andin a docs build that starts at
_startand runs throughmakedocs.1253 assertions, green; docs build clean.
🤖 Generated with Claude Code