You are viewing a plain text version of this content. The canonical link for it is here.
Posted to issues@iceberg.apache.org by "laskoviymishka (via GitHub)" <gi...@apache.org> on 2026/04/18 19:31:46 UTC
[PR] docs(website): add generator scaffold for example-driven concept pages [iceberg-go]
laskoviymishka opened a new pull request, #920:
URL: https://github.com/apache/iceberg-go/pull/920
Introduces website/gen, a small stdlib-only program that walks the repo for example_*_test.go files carrying an `iceberg:doc` header and regenerates the Concepts section of the mdbook site from them. Code blocks will be emitted as mdbook `{{#include file:anchor}}` directives, so the compiled test, not a hand-maintained snippet, is the source of truth for each example.
No test file carries the header yet, so the generator is a no-op at this point; it exits 0 with a log line.
This PR is more a question - should we already automate generation of docs? cc @zeroshade / @kevinjqliu.
If yes - after merge i'll do a follow-up PR will anchor the existing examples, add the SUMMARY marker block, commit the first generated page, and wire the CI gate.
Adds a `docs-gen` Makefile target so `make docs-gen` regenerates the concepts in one command.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
Re: [PR] docs(website): add generator scaffold for example-driven concept pages [iceberg-go]
Posted by "laskoviymishka (via GitHub)" <gi...@apache.org>.
laskoviymishka commented on PR #920:
URL: https://github.com/apache/iceberg-go/pull/920#issuecomment-4287953767
One more thought on the sibling-projects angle, since I think it's actually the load-bearing argument here:
[pyiceberg](https://github.com/apache/iceberg-python/blob/main/mkdocs/docs/api.md) and the Java site both hand-write code blocks inline, and that works for them, but both are very mature, slow-moving libraries where the spec-surface cadence is low enough that human diligence keeps the docs roughly aligned with the code.
iceberg-go is in a different phase. Within the last release cycle alone we've shipped multi-table transactions, equality deletes (read + write + partitioned), compaction (Analyze + RewriteDataFiles + bin-pack), RowDelta, commit-conflict retry, multi-arg transforms, write/initial-default enforcement, and V3 preview pieces like row lineage and nanosecond timestamps. Hand-maintained docs fall behind that cadence almost immediately.
The user-visible effect is worse than "slightly stale." Someone lands on go.iceberg.apache.org, sees a feature matrix with half the cells empty and a code sample that doesn't compile against the current API, and concludes the library is less mature than it actually is. That's a perception gap we close for free by making the compiled test the source of truth — the maintenance cost is the test you were going to write anyway, and `mdbook build` + the CI gate guarantee the site can never drift from it.
Once iceberg-go's cadence matches pyiceberg/Java, the automation becomes less essential. Right now, it's the thing that lets the website keep pace with the code without asking contributors to do the duplicate work of pasting snippets by hand and hoping nobody notices when they rot.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
Re: [PR] docs(website): add generator scaffold for example-driven concept pages [iceberg-go]
Posted by "zeroshade (via GitHub)" <gi...@apache.org>.
zeroshade merged PR #920:
URL: https://github.com/apache/iceberg-go/pull/920
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
Re: [PR] docs(website): add generator scaffold for example-driven concept pages [iceberg-go]
Posted by "zeroshade (via GitHub)" <gi...@apache.org>.
zeroshade commented on PR #920:
URL: https://github.com/apache/iceberg-go/pull/920#issuecomment-4284076425
I like the idea here conceptually, alternately we can also point to the examples that end up available via pkg.go.dev docs for the package?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
Re: [PR] docs(website): add generator scaffold for example-driven concept pages [iceberg-go]
Posted by "laskoviymishka (via GitHub)" <gi...@apache.org>.
laskoviymishka commented on PR #920:
URL: https://github.com/apache/iceberg-go/pull/920#issuecomment-4287892143
Great point, and I think the honest answer is "both", they're complementary, not alternatives.
`pkg.go.dev` Examples are great for API reference:
`Example_foo` functions compile,
`// Output:` gets executed, and they show up right next to the symbol they illustrate.
We should absolutely keep writing them and link out to them from every concept page we generate.
What `pkg.go.dev` can't do is narrate. A concept page like "Row-level deletes" has to interleave prose with steps, group four related Example functions into a flow, link across chapters, and render headings inside code-adjacent commentary: godoc explicitly doesn't render any of that ([pkg.go.dev/about](https://pkg.go.dev/about)).
The pattern this PR proposes is what [uber-go/fx does with mkdocs snippets](https://github.com/uber-go/fx/blob/master/docs/src/get-started/minimal.md) (code in [`docs/ex/`](https://github.com/uber-go/fx/tree/master/docs/ex), pulled in via region markers) and what [the Rust Book does with `{{#rustdoc_include}}`](https://rust-lang.github.io/mdBook/format/mdbook.html) ([listings/](https://github.com/rust-lang/book/tree/main/listings)). In both cases the compiled test is the source of truth, not hand-pasted fences.
The counterexample worth calling out is our sibling projects: [pyiceberg's api.md](https://github.com/apache/iceberg-python/blob/main/mkdocs/docs/api.md) and the Java site both hand-write code blocks inline, which is fine until something like `newScan()` renames and nobody notices for two releases. But since it's a public API risk is minimal.
If it looks like overkill after that, we close the generator and I'll just add `pkg.go.dev` links to the existing hand-written pages.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org