docs: drop checked-in stardoc output in favour of BCR

[xnox]

Summary

registry.bazel.build already renders the full Starlark API for this module, generated from the sources. Keeping stardoc output checked in duplicates that and needs a test to hold the two in sync — a test that costs about 900 actions per CI run.

This removes docs/, points the README at https://registry.bazel.build/modules/rules_apko/latest/docs, and collapses the CI branch that existed only to work around stardoc.

The BCR docs are live today

No opt-in was needed. The page reports:

Starlark API Documentation — Auto-generated documentation using best-effort extraction method.
Extracted 5 of 5 files (100.0%)

All five module files are covered — apko/defs.bzl, extensions.bzl, repositories.bzl, toolchain.bzl, translate_lock.bzl — including apko_image, apko_config, apko_show_config, apko_lock, apko_toolchain, both providers, the apko module extension, translate_apko_lock, and the exported template values. That is a superset of what docs/rules.md and docs/translate_lock.md contained.

docs/apko-cache.md is folded into the README, not deleted

It was hand-written rather than generated — it carried a linguist-generated=false entry in .gitattributes — and BCR renders Starlark API docs, not arbitrary markdown. Its content moves into README.md as a ## Fetching and Caching Contents section, unchanged apart from heading levels. The BCR page links View README, so it stays reachable from where users land.

translate_lock.bzl and apko_image.bzl linked to it with paths relative to docs/. Those docstrings are exactly what BCR renders, where a relative link has no meaningful base, so they now use absolute URLs pointing at that README section.

CI

With the docs tests gone, bazel test //... no longer builds stardoc, protoc, or the protobuf Java runtime. Locally that takes //... from 976 actions / 322s to 35 actions / 10.9s.

That also removes the reason for the version split in the test matrix:

-      - name: Test
-        if: ${{ matrix.bazelversion >= '9.' || matrix.folder != '.' }}
-        run: bazel test //...
-      # Stardoc has output changes between versions
-      - name: Test no doc 8 and lower
-        if: ${{ matrix.bazelversion <= '8.' && matrix.folder == '.' }}
-        run: bazel query 'tests(//...) except docs/...' | xargs bazel test
+      - name: Test
+        run: bazel test //...

Every matrix cell now runs the same command. The stardoc dev dependency drops out of MODULE.bazel since nothing loads it.

The bzl_library targets in //apko stay — they are what a starlark_doc_extract would need if you ever want the guaranteed extraction path (publishing {REPO}-{TAG}.docs.tar.gz and a docs_url in .bcr/source.template.json) instead of best-effort.

Trade-off

BCR documents released versions only. There is no rendered API reference for unreleased main, whereas docs/*.md tracked the working tree. In exchange the docs can never drift from the sources, because they are generated from them at publish time.

Test plan

• bazel test //... — 4/4 pass
• bazel run //.github/workflows:buildifier.check — clean
• actionlint — unchanged (the pre-existing SC2086 findings in ci.yaml remain)
• grep for apko-cache.md, docs/rules.md, docs/translate_lock.md and ./docs/ across the tree returns nothing

🤖 Generated with Claude Code