docs: generate bzlmod extension docs (#1169)

- Upgrade [bazel-starlib](https://github.com/cgrindel/bazel-starlib) to
0.21.0 to pickup a version of stardoc that supports bzmod documentation
generation.
- Generate documentation for `swift_deps` bzlmod extension.

Closes #1168.

Author: cgrindel

BUILD.bazel

@@ -11,6 +11,9 @@ load(
 )
 load("//ci:defs.bzl", "ci_workflow")
 
+# Allow docs to access the extensions.bzl
+exports_files(["extensions.bzl"])
+
 # MARK: - Bazel Starlark Lint and Formatting
 
 bzlformat_pkg(name = "bzlformat")

MODULE.bazel

@@ -5,7 +5,7 @@ module(
 
 # MARK: - Runtime Dependencies
 
-bazel_dep(name = "cgrindel_bazel_starlib", version = "0.18.1")
+bazel_dep(name = "cgrindel_bazel_starlib", version = "0.21.0")
 bazel_dep(name = "bazel_skylib", version = "1.4.2")
 bazel_dep(
     name = "rules_go",

docs/BUILD.bazel

@@ -40,6 +40,13 @@ _DOC_INFOS = [
             "swift_deps_index",
         ],
     ),
+    doc_infos.new(
+        name = "bzlmod_extensions",
+        label = "//:extensions",
+        symbols = [
+            "swift_deps",
+        ],
+    ),
 ]
 
 _DOC_WITH_SYMBOLS = {
@@ -98,6 +105,19 @@ external Swift packages.
     symbols = _DOC_WITH_SYMBOLS["internal_rules_and_macros"].symbols,
 )
 
+write_header(
+    name = "bzlmod_extensions_overview_header",
+    header_content = [
+        "# Bazel Modules (bzlmod) Extensions",
+        "",
+        """
+The bzlmod extensions described below are used by `rules_swift_package_manager` \
+to customize the build of the external Swift packages.\
+""",
+    ],
+    symbols = _DOC_WITH_SYMBOLS["bzlmod_extensions"].symbols,
+)
+
 doc_for_provs(doc_provs = _ALL_DOC_PROVIDERS)
 
 bzl_library(

docs/bzlmod_extensions_overview.md

@@ -0,0 +1,59 @@
+<!-- Generated with Stardoc, Do Not Edit! -->
+# Bazel Modules (bzlmod) Extensions
+
+
+The bzlmod extensions described below are used by `rules_swift_package_manager` to customize the build of the external Swift packages.
+
+On this page:
+
+  * [swift_deps](#swift_deps)
+
+
+<a id="swift_deps"></a>
+
+## swift_deps
+
+<pre>
+swift_deps = use_extension("@rules_swift_package_manager//:extensions.bzl", "swift_deps")
+swift_deps.configure_package(<a href="#swift_deps.configure_package-name">name</a>, <a href="#swift_deps.configure_package-init_submodules">init_submodules</a>, <a href="#swift_deps.configure_package-patch_args">patch_args</a>, <a href="#swift_deps.configure_package-patch_cmds">patch_cmds</a>, <a href="#swift_deps.configure_package-patch_cmds_win">patch_cmds_win</a>,
+                             <a href="#swift_deps.configure_package-patch_tool">patch_tool</a>, <a href="#swift_deps.configure_package-patches">patches</a>, <a href="#swift_deps.configure_package-recursive_init_submodules">recursive_init_submodules</a>)
+swift_deps.from_package(<a href="#swift_deps.from_package-declare_swift_deps_info">declare_swift_deps_info</a>, <a href="#swift_deps.from_package-resolved">resolved</a>, <a href="#swift_deps.from_package-swift">swift</a>)
+</pre>
+
+
+**TAG CLASSES**
+
+<a id="swift_deps.configure_package"></a>
+
+### configure_package
+
+Used to add or override settings for a particular Swift package.
+
+**Attributes**
+
+| Name  | Description | Type | Mandatory | Default |
+| :------------- | :------------- | :------------- | :------------- | :------------- |
+| <a id="swift_deps.configure_package-name"></a>name |  The identity (i.e., name in the package's manifest) for the Swift package.   | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required |  |
+| <a id="swift_deps.configure_package-init_submodules"></a>init_submodules |  Whether to clone submodules in the repository.   | Boolean | optional |  `False`  |
+| <a id="swift_deps.configure_package-patch_args"></a>patch_args |  The arguments given to the patch tool. Defaults to -p0, however -p1 will usually be needed for patches generated by git. If multiple -p arguments are specified, the last one will take effect.If arguments other than -p are specified, Bazel will fall back to use patch command line tool instead of the Bazel-native patch implementation. When falling back to patch command line tool and patch_tool attribute is not specified, `patch` will be used.   | List of strings | optional |  `["-p0"]`  |
+| <a id="swift_deps.configure_package-patch_cmds"></a>patch_cmds |  Sequence of Bash commands to be applied on Linux/Macos after patches are applied.   | List of strings | optional |  `[]`  |
+| <a id="swift_deps.configure_package-patch_cmds_win"></a>patch_cmds_win |  Sequence of Powershell commands to be applied on Windows after patches are applied. If this attribute is not set, patch_cmds will be executed on Windows, which requires Bash binary to exist.   | List of strings | optional |  `[]`  |
+| <a id="swift_deps.configure_package-patch_tool"></a>patch_tool |  The patch(1) utility to use. If this is specified, Bazel will use the specified patch tool instead of the Bazel-native patch implementation.   | String | optional |  `""`  |
+| <a id="swift_deps.configure_package-patches"></a>patches |  A list of files that are to be applied as patches after extracting the archive. By default, it uses the Bazel-native patch implementation which doesn't support fuzz match and binary patch, but Bazel will fall back to use patch command line tool if `patch_tool` attribute is specified or there are arguments other than `-p` in `patch_args` attribute.   | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional |  `[]`  |
+| <a id="swift_deps.configure_package-recursive_init_submodules"></a>recursive_init_submodules |  Whether to clone submodules recursively in the repository.   | Boolean | optional |  `True`  |
+
+<a id="swift_deps.from_package"></a>
+
+### from_package
+
+Load Swift packages from `Package.swift` and `Package.resolved` files.
+
+**Attributes**
+
+| Name  | Description | Type | Mandatory | Default |
+| :------------- | :------------- | :------------- | :------------- | :------------- |
+| <a id="swift_deps.from_package-declare_swift_deps_info"></a>declare_swift_deps_info |  Declare a `swift_deps_info` repository that is used by external tooling (e.g. Swift Gazelle plugin).   | Boolean | optional |  `False`  |
+| <a id="swift_deps.from_package-resolved"></a>resolved |  A `Package.resolved`.   | <a href="https://bazel.build/concepts/labels">Label</a> | optional |  `None`  |
+| <a id="swift_deps.from_package-swift"></a>swift |  A `Package.swift`.   | <a href="https://bazel.build/concepts/labels">Label</a> | required |  |
+
+

docs/internal_rules_and_macros_overview.md

@@ -28,10 +28,10 @@ Generate a modulemap for an Objective-C module.
 | Name  | Description | Type | Mandatory | Default |
 | :------------- | :------------- | :------------- | :------------- | :------------- |
 | <a id="generate_modulemap-name"></a>name |  A unique name for this target.   | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required |  |
-| <a id="generate_modulemap-deps"></a>deps |  The module maps that this module uses.   | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | <code>[]</code> |
+| <a id="generate_modulemap-deps"></a>deps |  The module maps that this module uses.   | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional |  `[]`  |
 | <a id="generate_modulemap-hdrs"></a>hdrs |  The public headers for this module.   | <a href="https://bazel.build/concepts/labels">List of labels</a> | required |  |
-| <a id="generate_modulemap-module_name"></a>module_name |  The name of the module.   | String | optional | <code>""</code> |
-| <a id="generate_modulemap-noop"></a>noop |  Designates whether a modulemap should be generated. If <code>False</code>, a modulemap is generated. If <code>True</code>, a modulemap file is not generated and the returned providers are empty.   | Boolean | optional | <code>False</code> |
+| <a id="generate_modulemap-module_name"></a>module_name |  The name of the module.   | String | optional |  `""`  |
+| <a id="generate_modulemap-noop"></a>noop |  Designates whether a modulemap should be generated. If `False`, a modulemap is generated. If `True`, a modulemap file is not generated and the returned providers are empty.   | Boolean | optional |  `False`  |
 
 
 <a id="resource_bundle_accessor"></a>
@@ -69,6 +69,6 @@ Generate an Info.plist for an SPM resource bundle.
 | Name  | Description | Type | Mandatory | Default |
 | :------------- | :------------- | :------------- | :------------- | :------------- |
 | <a id="resource_bundle_infoplist-name"></a>name |  A unique name for this target.   | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required |  |
-| <a id="resource_bundle_infoplist-region"></a>region |  The localization/region value that should be embedded in the Info.plist.   | String | optional | <code>"en"</code> |
+| <a id="resource_bundle_infoplist-region"></a>region |  The localization/region value that should be embedded in the Info.plist.   | String | optional |  `"en"`  |