SIG Docs and You: Modernizing API Reference Generation
Talkat KubeCon + CloudNativeCon Europe 2025 · on Thursday, 2025-04-03· at 16:45· Platinum Suite | Level 3 | Room 3-4·
summary
Process requires cloning multiple repos, setting GOPATHs, and running a brittle generator that must run generation twice for Kubernetes and kubectl. The bash wrapper calls a Python script that calls Go and fails predictably during API copy/markdown generation, forcing manual edits to generated files every release. Only one or two maintainers can complete it now; error messages are unhelpful and code is undocumented. Goals are documented setup, contributor-friendly cleanup, and a rewrite that leverages existing OpenAPI tooling rather than custom code.
AI-written summary · about
chapters (8)
- 0:00Welcome
- 0:43Current process
- 3:14Flaws in workflow
- 5:18Modernization goals
- 6:43Contributor expectations
- 7:27How to help
- 8:13Future vision
- 9:40Q&A
related talks
45mDocs That Scale: Strategies for Sustainable Documentation in Open Source Projects
35mDocumenting APIs: new era, same craft
24mEscaping the Curse of Outdated Docs
44mPushing documentation (so it doesn't hurt anymore)
34mSIG Contributor Experience Deep Dive
38mSharing Knowledge: Writing Good Docs for Quick Approval
44mgogoprotobuf: How NOT to run an open source project
32mTransform Your OpenAPI Spec into Interactive, AI-Powered