Switch to Bzlmod by default for managing external dependencies

.bazelci/presubmit.yml

@@ -8,19 +8,15 @@ matrix:
 .common_flags: &common_flags
   ? "--incompatible_disable_starlark_host_transitions"
 
-.bzlmod_flags: &bzlmod_flags
+.noenable_bzlmod_flags: &noenable_bzlmod_flags
   <<: *common_flags
-  ? "--enable_bzlmod"
+  ? "--noenable_bzlmod"
 
 .windows_flags: &windows_flags
   <<: *common_flags
   # Workaround for https://github.com/bazelbuild/continuous-integration/issues/1012
   ? "--noexperimental_repository_cache_hardlinks"
 
-.windows_bzlmod_flags: &windows_bzlmod_flags
-  <<: *windows_flags
-  ? "--enable_bzlmod"
-
 .common_task_config: &common_task_config
   build_flags: *common_flags
   build_targets:
@@ -29,21 +25,31 @@ matrix:
   test_targets:
     - "//..."
 
-.bzlmod_task_config: &bzlmod_task_config
-  <<: *common_task_config
-  build_flags: *bzlmod_flags
-  test_flags: *bzlmod_flags
+.noenable_bzlmod_task_config: &noenable_bzlmod_task_config
+  build_flags: *noenable_bzlmod_flags
+  build_targets:
+  # Note that //distro/... cannot be loaded in legacy WORKSPACE mode due to repo name change
+    - "//:*"
+    - "//src/..."
+    - "//stardoc/..."
+    - "//test/..."
+  test_flags: *noenable_bzlmod_flags
+  test_targets:
+  # Some tests are expected to fail in legacy WORKSPACE mode due to repo name change
+    - "//test/..."
+    - "-//test:attribute_defaults_test_e2e_test"
+    - "-//test:function_wrap_multiple_lines_test_e2e_test"
+    - "-//test:misc_apis_test_e2e_test"
+    - "-//test:module_extension_test_e2e_test"
+    - "-//test:proto_format_test_e2e_test"
+    - "-//test:stardoc_self_gen_test"
+    - "-//test:table_of_contents_test_e2e_test"
 
 .windows_task_config: &windows_task_config
   <<: *common_task_config
   build_flags: *windows_flags
   test_flags: *windows_flags
 
-.windows_bzlmod_task_config: &windows_bzlmod_task_config
-  <<: *common_task_config
-  build_flags: *windows_bzlmod_flags
-  test_flags: *windows_bzlmod_flags
-
 tasks:
   build_and_test:
     <<: *common_task_config
@@ -55,6 +61,11 @@ tasks:
     name: Build and test - Windows
     platform: windows
 
+  legacy_workspace:
+    <<: *noenable_bzlmod_task_config
+    name: Build and test - legacy WORKSPACE setup
+    platform: ${{ platform }}
+
   build_and_test_last_green:
     <<: *common_task_config
     name: Build and test - Bazel last green
@@ -67,15 +78,15 @@ tasks:
     platform: windows
     bazel: last_green
 
-  bzlmod:
-    <<: *bzlmod_task_config
-    name: Bzlmod example
+  bzlmod_usage:
+    <<: *common_task_config
+    name: Stardoc Bzlmod module usage test
     platform: ${{ platform }}
     working_directory: test/bzlmod
 
-  bzlmod_windows:
-    <<: *windows_bzlmod_task_config
-    name: Bzlmod example - Windows
+  bzlmod_usage_windows:
+    <<: *windows_task_config
+    name: Stardoc Bzlmod module usage test - Windows
     platform: windows
     working_directory: test/bzlmod
 

.bazelrc

@@ -1,6 +1,2 @@
 build --java_language_version=11
 build --tool_java_language_version=11
-
-# TODO: migrate all dependencies from WORKSPACE to MODULE.bazel
-# https://github.com/bazelbuild/stardoc/issues/189
-common --noenable_bzlmod

BUILD

@@ -19,6 +19,7 @@ exports_files(
 exports_files(
     [
         "WORKSPACE",
+        "WORKSPACE.bzlmod",
         "MODULE.bazel",
         "deps.bzl",
         "version.bzl",

MODULE.bazel

@@ -1,6 +1,7 @@
 module(
     name = "stardoc",
     version = "0.7.0-pre",
+    bazel_compatibility = [">=7.0.0"],
     compatibility_level = 1,
 )
 
@@ -31,3 +32,6 @@ maven.install(
     strict_visibility = True,
 )
 use_repo(maven, "stardoc_maven")
+
+# Dev-only and test-only dependencies
+bazel_dep(name = "rules_pkg", version = "0.10.1", dev_dependency = True)

WORKSPACE

@@ -57,10 +57,9 @@ bind(
 # Needed for //distro:__pkg__
 http_archive(
     name = "rules_pkg",
-    sha256 = "eea0f59c28a9241156a47d7a8e32db9122f3d50b505fae0f33de6ce4d9b61834",
+    sha256 = "d250924a2ecc5176808fc4c25d5cf5e9e79e6346d79d5ab1c493e289e722d1d0",
     urls = [
-        "https://mirror.bazel.build/github.com/bazelbuild/rules_pkg/releases/download/0.8.0/rules_pkg-0.8.0.tar.gz",
-        "https://github.com/bazelbuild/rules_pkg/releases/download/0.8.0/rules_pkg-0.8.0.tar.gz",
+        "https://github.com/bazelbuild/rules_pkg/releases/download/0.10.1/rules_pkg-0.10.1.tar.gz",
     ],
 )
 
@@ -79,6 +78,11 @@ http_archive(
 )
 
 # Needed only for testing stardoc across local-repository bounds.
+local_repository(
+    name = "stardoc",  # alias the Bzlmod name of the Stardoc repo for local_repository_test
+    path = ".",
+)
+
 local_repository(
     name = "local_repository_test",
     path = "test/testdata/local_repository_test",

WORKSPACE.bzlmod

@@ -0,0 +1,7 @@
+### INTERNAL ONLY - lines after this are not included in the release packaging.
+
+# Needed only for testing stardoc across local-repository bounds.
+local_repository(
+    name = "local_repository_test",
+    path = "test/testdata/local_repository_test",
+)

distro/BUILD

@@ -1,5 +1,6 @@
-load("@io_bazel_stardoc//:version.bzl", "version")
 load("@rules_pkg//:pkg.bzl", "pkg_tar")
+load("@stardoc//:version.bzl", "version")
+load(":distro.bzl", "strip_internal_only")
 
 package(
     default_applicable_licenses = ["//:license"],
@@ -11,17 +12,23 @@ alias(
     actual = "stardoc-%s" % version,
 )
 
-genrule(
+strip_internal_only(
     name = "distro_workspace",
-    srcs = ["//:WORKSPACE"],
-    outs = ["WORKSPACE"],
-    cmd = "sed -e '/### INTERNAL ONLY/,/### END INTERNAL ONLY/d' $(location //:WORKSPACE) >$@",
+    src = "//:WORKSPACE",
+    out = "WORKSPACE",
+)
+
+strip_internal_only(
+    name = "distro_workspace_bzlmod",
+    src = "//:WORKSPACE.bzlmod",
+    out = "WORKSPACE.bzlmod",
 )
 
 pkg_tar(
     name = "distro_srcs",
     srcs = [
         "distro_workspace",
+        "distro_workspace_bzlmod",
         "//:distro_srcs",
     ],
     mode = "0644",

distro/distro.bzl

@@ -0,0 +1,18 @@
+"""Macros related to distro tarball packaging"""
+
+def strip_internal_only(name, src, out):
+    """Strip an internal-only block from a file
+
+    Removes everything starting with `### INTERNAL ONLY` and ending with `### END INTERNAL ONLY` (or up to the end of the file).
+
+    Args:
+        name: Target name
+        src: Input file
+        out: Output file
+    """
+    native.genrule(
+        name = name,
+        srcs = [src],
+        outs = [out],
+        cmd = "sed -e '/### INTERNAL ONLY/,/### END INTERNAL ONLY/d' $(location %s) >$@" % src,
+    )

docs/advanced_stardoc_usage.md

@@ -18,7 +18,7 @@ to your Starlark code. Use standard markdown formatting constructs instead of
 HTML tags.
 
 For example:
-```python
+```starlark
 def my_function(foo, bar):
   """Does some cool stuff.
 
@@ -109,7 +109,7 @@ To configure stardoc to output raw proto instead of markdown, use the `format`
 attribute of the [stardoc rule](stardoc_rule.md#stardoc-format). Specify `"proto"`.
 An example:
 
-```python
+```starlark
 stardoc(
     name = "docs_proto_output",
     out = "doc_output.raw",
@@ -121,7 +121,7 @@ stardoc(
 # Define a proto_library target to incorporate the stardoc_output_proto
 proto_library(
     name = "stardoc_output_proto",
-    srcs = ["@io_bazel_stardoc//stardoc/proto:stardoc_output.proto"],
+    srcs = ["@stardoc//stardoc/proto:stardoc_output.proto"],
 )
 
 # You'll need to define your own rendering target. This might be a

docs/generating_stardoc.md

@@ -9,6 +9,11 @@
 
 The following are some examples of how to use Stardoc.
 
+**Note**: By default - in other words, when using Bzlmod for dependency
+management - Stardoc uses `@stardoc` as its repo name. However, if you are
+using the legacy `WORSKPACE`-based setup for dependency management, replace
+`@stardoc` with `@io_bazel_stardoc` in the examples below.
+
 <a name="single-file"></a>
 ## Single File
 
@@ -25,8 +30,8 @@ Suppose you have a project containing Stardoc rules you want to document:
 To generate documentation for the rules in `checkstyle.bzl`, add the
 following target to `checkstyle/BUILD`:
 
-```python
-load("@io_bazel_stardoc//stardoc:stardoc.bzl", "stardoc")
+```starlark
+load("@stardoc//stardoc:stardoc.bzl", "stardoc")
 
 stardoc(
     name = "checkstyle-docs",
@@ -43,8 +48,8 @@ rule names you specifically want documentation for using the `symbol_names` attr
 of the `stardoc` rule. If `symbol_names` is specified, only rules matching a name
 in `symbol_names` will be documented:
 
-```python
-load("@io_bazel_stardoc//stardoc:stardoc.bzl", "stardoc")
+```starlark
+load("@stardoc//stardoc:stardoc.bzl", "stardoc")
 
 stardoc(
     name = "checkstyle-docs",
@@ -81,7 +86,7 @@ Suppose your project has the following structure:
 
 `checkstyle/checkstyle.bzl`:
 
-```python
+```starlark
 load("//lua:lua.bzl", "lua_utility")
 
 lua_utility()
@@ -112,8 +117,8 @@ as a dependency of the `stardoc` target:
 
 `checkstyle/BUILD`:
 
-```python
-load("@io_bazel_stardoc//stardoc:stardoc.bzl", "stardoc")
+```starlark
+load("@stardoc//stardoc:stardoc.bzl", "stardoc")
 
 stardoc(
     name = "checkstyle-docs",
@@ -137,7 +142,7 @@ which loads these files and binds the rules to be documented as globals:
 
 `doc_hub.bzl`:
 
-```python
+```starlark
 load("//foo:foo.bzl", _foo_rule = "foo_rule")
 load("//bar:bar.bzl", _bar_rule = "bar_rule")
 load("//baz:baz.bzl", _baz_rule = "baz_rule")
@@ -154,7 +159,7 @@ A single `stardoc` target can then be used to generate their documentation:
 `BUILD`:
 
 ```python
-load("@io_bazel_stardoc//stardoc:stardoc.bzl", "stardoc")
+load("@stardoc//stardoc:stardoc.bzl", "stardoc")
 
 stardoc(
     name = "my-docs",

docs/getting_started_stardoc.md

@@ -12,17 +12,34 @@ extensions](https://bazel.build/extending/concepts)
 
 ## Setup
 
+Add a `bazel_dep` invocation for Stardoc to your `MODULE.bazel` file, as shown
+in the `MODULE.bazel` setup section for
+[the current Stardoc release](https://github.com/bazelbuild/stardoc/releases).
+
+Then add
+
+```starlark
+load("@stardoc//stardoc:stardoc.bzl", "stardoc")
+```
+
+to your `BUILD` or .bzl file to start using the `stardoc` rule.
+
+## Legacy WORKSPACE setup
+
 Edit your `WORKSPACE` file as shown in the `WORKSPACE` setup section for
 [the current Stardoc release](https://github.com/bazelbuild/stardoc/releases).
 
 Then add
 
-```python
+```starlark
 load("@io_bazel_stardoc//stardoc:stardoc.bzl", "stardoc")
 ```
 
 to your `BUILD` or .bzl file to start using the `stardoc` rule.
 
+Note that if you are using `WORKSPACE` for dependency management, Stardoc's
+repo name is `@io_bazel_stardoc`, not `@stardoc`.
+
 ## Next Steps
 
 Now you are ready to document your Starlark rules.

docs/maintainers_guide.md

@@ -63,7 +63,19 @@ Name 1, Name 2, Name 3 (alphabetically)
 
 --------------------------------------------------------------------------------
 
-**WORKSPACE setup**
+**MODULE.bazel setup**
+
+```starlark
+bazel_dep(name = "stardoc", version = "$VERSION")
+```
+
+By default - in other words, when using Bzlmod for dependency management -
+Stardoc uses `@stardoc` as its repo name. The legacy `WORSKSPACE` setup (see
+below) used `@io_bazel_stardoc` instead. For compatibility with the legacy
+`WORKSPACE` setup, you may add `repo_name = "io_bazel_stardoc"` to the
+`bazel_dep` call.
+
+**Legacy WORKSPACE setup**
 
 To use Stardoc, add the following to your `WORKSPACE` file:
 
@@ -111,17 +123,6 @@ maven_install.json file" or other repository fetch errors (example: #186), try
 moving the Stardoc dependency block above or below other dependencies in your
 `WORKSPACE` file.
 
-<!-- Uncomment after updating Stardoc in Bazel Central Registry
-**MODULE.bazel setup**
-
-```starlark
-bazel_dep(name = "stardoc", version = "$VERSION")
-```
-
-For compatibility with `WORKSPACE` setup, add `repo_name = "io_bazel_stardoc"`
-to the `bazel_dep` call.
--->
-
 **Using the rules**
 
 See [the source](https://github.com/bazelbuild/stardoc/tree/$VERSION).

docs/skydoc_deprecation.md

@@ -84,7 +84,7 @@ depends on `third/package/baz.bzl`.
 **BUILD**:
 
 ```python
-load("@io_bazel_stardoc//stardoc:stardoc.bzl", "stardoc")
+load("@stardoc//stardoc:stardoc.bzl", "stardoc")
 
 stardoc(
     name = "foo_docs",