Per-page rendering and reproducible output for library consumers

[ewels]

Two gaps blocked a downstream consumer — they generate docs in a build hook, currently by shelling out to nf-docs, and want to switch to the library API from #14. Their acceptance criterion was deleting two workarounds: a temp-folder round-trip, and code that strips the generated footer.

1. Per-page markdown as strings

render() returns one combined document, and the per-page Markdown was only reachable via render_to_directory(), which writes files. So consuming pages in memory meant generating into a temporary directory and reading them back.

BaseRenderer.render_pages(pipeline) -> dict[str, str] returns the same content keyed by filename, with nf_docs.render_pages() alongside render() on the facade:

pages = nf_docs.render_pages(pipeline, "markdown")

for filename, content in pages.items():
    my_site.add_page(f"api/{filename}", content)

render_to_directory() moved into the base class and now just writes what render_pages() returns, which drops the duplicated write loop from four of the five renderers. render_pages() is the abstract method in its place.

TableRenderer keeps its own render_to_directory(). It reads the existing README.md and, if it finds the BEGIN_NF_DOCS / END_NF_DOCS markers, injects between them, honouring {{ section }} template tags. That output depends on what's already in the destination, so it isn't expressible as dict[str, str]. Its render_pages() returns the standalone marker-wrapped form — the same bytes render_to_directory() writes into an empty directory — and a test asserts the two genuinely diverge when a marker README already exists.

Keys are conditional. Markdown always returns index.md and inputs.md, and adds config.md, workflows.md, processes.md and functions.md only when the pipeline has the corresponding entries. That's six possible pages, not the five originally reported. The docs say plainly not to assume a fixed set.

render_pages() defaults to html like render() and generate(), even though markdown is the format it exists for — a facade where one function silently defaults differently is a trap.

2. Reproducible output

The request was footer=False, but that only covers markdown and table. Every place generation metadata is injected:

Format	Timestamp?	Where
markdown	yes	get_markdown_footer()
table	yes	get_markdown_footer()
json	yes, microsecond resolution	data["generated_by"]
html	yes	get_generation_timestamp()
yaml	no	already reproducible

So footer=False would leave them stripping output for anything but markdown. Instead, BaseRenderer takes include_generation_info: bool = True, covering every format. Being a renderer option, it reaches render(), render_pages() and generate() through the existing **renderer_kwargs with no plumbing.

It's keyword-only, so it can't collide with the positional indent / use_tailwind / default_flow_style.

HTML keeps its Documentation generated by nf-docs v0.4.0 line and the Nextflow attribution — both identical on every build from a given install — and drops only the timestamp beside them.

Verification

The tests assert the actual requirement: render the same pipeline twice, per format, and compare bytes. Worth noting, because a naive version of that test passes no matter what the flag does — the suite finishes inside a single wall-clock second, so the timestamps match by accident. A stub clock in conftest.py advances a second per call, and a guard test asserts output does vary with generation info on.

Also verified independently outside pytest with real sleep between renders: reproducible with the flag off, varying with it on, for every format except YAML.

425 tests pass. ruff check, ruff format --check, ty check and prettier clean. The html.html edit adds no class names, and a real Tailwind rebuild leaves tailwind.css byte-identical.

Notes for review

• BaseRenderer's abstract surface changed. render_to_directory() → render_pages(). The five built-in renderers are unaffected, but a subclass outside this repo that implemented only render_to_directory() now needs a render_pages() too. Called out under Changed in the CHANGELOG.
• HTML still isn't fully reproducible, and this flag can't fix it. When a pipeline has a GitHub repository, get_repository_avatar_data_url() fetches the org avatar over the network and inlines it at render time, so a failed request or a changed avatar changes the page. That's content rather than generation metadata, so it's out of scope here — but since the stated requirement is byte-identical builds, it's flagged in a docs warning rather than left to be discovered.
• CLI unchanged. No --no-generation-info flag; this was scoped to the library API. Easy to add if you want it.

🤖 Generated with Claude Code

https://claude.ai/code/session_01922CMQ76XwtfSr5ZgYJ8rj

---

Generated by Claude Code