feat: publish stardocs on releases, rather than write_source_files (#160)

* feat: publish stardocs on release

* cleanup references to docgen

* Update release_prep.sh

* fixes

* updates

* don't test root on bazel 6

Author: alexeagle

.bcr/source.template.json

@@ -1,5 +1,6 @@
 {
   "integrity": "**leave this alone**",
   "strip_prefix": "{REPO}-{VERSION}",
+  "docs_url": "https://github.com/{OWNER}/{REPO}/releases/download/{TAG}/{REPO}-{TAG}.docs.tar.gz",
   "url": "https://github.com/{OWNER}/{REPO}/releases/download/{TAG}/{REPO}-{TAG}.tar.gz"
 }

.gitattributes

@@ -1,6 +1,3 @@
-# In code review, collapse generated files
-docs/*.md linguist-generated=true
-
 #################################
 # Configuration for 'git archive'
 # See https://git-scm.com/docs/git-archive#ATTRIBUTES

.github/workflows/ci.yaml

@@ -24,7 +24,8 @@ jobs:
         ]
       exclude: |
         [
-          {"folder": ".", "bzlmodEnabled": false}
+          {"folder": ".", "bzlmodEnabled": false},
+          {"folder": ".", "bazelVersion": "6.4.0"}
         ]
   pre-commit:
     runs-on: ubuntu-latest

.github/workflows/release_prep.sh

@@ -15,6 +15,14 @@ ARCHIVE="rules_mylang-$TAG.tar.gz"
 git archive --format=tar --prefix=${PREFIX}/ ${TAG} | gzip > $ARCHIVE
 SHA=$(shasum -a 256 $ARCHIVE | awk '{print $1}')
 
+# 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" .
+
 cat << EOF
 ## Using Bzlmod with Bazel 6 or greater
 

.pre-commit-config.yaml

@@ -24,10 +24,6 @@ repos:
       - id: destroyed-symlinks
       - id: detect-private-key
       - id: end-of-file-fixer
-        exclude: |
-          (?x)^(
-            docs/
-          )
       - id: trailing-whitespace
   # Check formatting and lint for starlark code
   - repo: https://github.com/keith/pre-commit-buildifier

.prettierignore

@@ -1 +0,0 @@
-docs/*.md

BUILD.bazel

@@ -18,6 +18,7 @@ license(
     text = "LICENSE",
 )
 
+# gazelle:map_kind bzl_library bzl_library @bazel_lib//:bzl_library.bzl
 gazelle_binary(
     name = "gazelle_bin",
     languages = ["@bazel_skylib_gazelle_plugin//bzl"],

MODULE.bazel

@@ -36,7 +36,7 @@ bazel_dep(name = "platforms", version = "0.0.5")
 
 bazel_dep(name = "gazelle", version = "0.35.0", dev_dependency = True, repo_name = "bazel_gazelle")
 bazel_dep(name = "bazel_skylib_gazelle_plugin", version = "1.4.1", dev_dependency = True)
-bazel_dep(name = "aspect_bazel_lib", version = "1.32.1", dev_dependency = True)
+bazel_dep(name = "bazel_lib", version = "3.0.0", dev_dependency = True)
 bazel_dep(name = "buildifier_prebuilt", version = "6.1.2", dev_dependency = True)
 
 mylang = use_extension("//mylang:extensions.bzl", "mylang")

README.md

@@ -7,7 +7,7 @@ Features:
 - follows the official style guide at https://bazel.build/rules/deploying
 - allows for both WORKSPACE.bazel and bzlmod (MODULE.bazel) usage
 - includes Bazel formatting as a pre-commit hook (using [buildifier])
-- includes stardoc API documentation generator
+- includes API documentation generation
 - includes typical toolchain setup
 - CI configured with GitHub Actions
 - release using GitHub Actions just by pushing a tag