docs: tell authors how to publish stardocs (#6209)

Fixes #5593

Author: alexeagle

docs/README.md

@@ -50,6 +50,12 @@ The tool also accepts a `--version` option to update the `source.json` of a spec
    # the target can also be your target that depends on this.
    ```
 
+### Documenting the module
+
+The `source.json` permits a `docs_url` attribute pointing to the documentation.
+
+This may optionally point to an archive file of stardoc_output.proto files, see [Stardoc API Docs](./stardoc.md).
+
 ## Presubmit
 
 Every module version must pass the BCR presubmit before getting merged. The presubmit validates the correctness and consistency of module information, then runs build and test targets specified in the `presubmit.yml` file. The BCR presubmit is driven by the [bcr_presubmit.py](https://github.com/bazelbuild/continuous-integration/blob/master/buildkite/bazel-central-registry/bcr_presubmit.py) script on [Bazel CI](https://github.com/bazelbuild/continuous-integration/tree/master/buildkite#bazel-continuous-integration).

docs/stardoc.md

@@ -0,0 +1,61 @@
+# Starlark API Documentation
+
+Modules that expose Starlark APIs (rulesets, for example) may choose to publish documentation as a reference URL on releases.
+
+Read more about this feature: https://blog.aspect.build/stardocs-on-bcr
+
+## Generating API docs
+
+The built-in rule [starlark_doc_extract](https://bazel.build/versions/8.3.0/reference/be/general#starlark_doc_extract) outputs `.binaryproto` files containing `stardoc_output.ModuleInfo` messages.
+
+- Source: https://github.com/bazelbuild/bazel/blob/master/src/main/protobuf/stardoc_output.proto
+- Docs: https://buf.build/bazel/bazel/docs/main:stardoc_output#stardoc_output.ModuleInfo
+
+Authors are free to generate these files however they choose.
+The simplest option is to add a `starlark_doc_extract` target for each `bzl_library` target you wish to document.
+
+Note that the `bzl_library` rule from `bazel_skylib` has `filegroup` semantics - it doesn't produce any outputs, nor verify that the `bzl_library` has all dependencies provided.
+See https://github.com/bazel-contrib/bazel-lib/blob/main/bzl_library.bzl for an alternative that fixes this. 
+
+It is wise to run `bazel query 'kind(starlark_doc_extract, //...)'` to confirm which starlark modules your ruleset documents.
+
+## Creating the docs artifact
+
+Users of the Publish-to-BCR workflow have an existing `.github/workflows/release_prep.sh` script.
+In this case you can simply add a snippet to create an archive file containing the stardoc output:
+
+```bash
+# Add generated API docs to the release, see https://github.com/bazelbuild/bazel-central-registry/issues/5593
+docs="$(mktemp -d)"; targets="$(mktemp)"
+bazel --output_base="$docs" query --output=label --output_file="$targets" 'kind("starlark_doc_extract rule", //...)'
+bazel --output_base="$docs" build --target_pattern_file="$targets"
+tar --create --auto-compress \
+    --directory "$(bazel --output_base="$docs" info bazel-bin)" \
+    --file "$GITHUB_WORKSPACE/${ARCHIVE%.tar.gz}.docs.tar.gz" .
+```
+
+> [!IMPORTANT]
+> The `--output_file` flag was added in Bazel 7.5.0
+
+Of course authors are free to produce the docs archive using a different technique.
+
+## Publishing the docs
+
+Again, we assume use of Publish-to-BCR.
+
+Edit `.bcr/source.template.json` to include a link, such as
+
+```json
+{
+    ...
+    "docs_url": "https://github.com/{OWNER}/{REPO}/releases/download/{TAG}/{REPO}-{TAG}.docs.tar.gz",
+}
+```
+
+> [!IMPORTANT]
+> publish-to-bcr version v0.2.3 or greater is required to pick up a fix for multiple replacements in source.template.json
+
+## Rendered docs
+
+The https://registry.bazel.build site renders stardocs for modules that have published them.
+The code for that site is in https://github.com/bazel-contrib/bcr-ui.