chore: generate Starlark documentation

README.md

@@ -1,9 +1,9 @@
 # Gazelle Plugin for Swift and Swit Package Rules for Bazel
 
 This repository contains a [Gazelle plugin] and Bazel repository rules that can be used to download,
-build, and consume Swift packages with [rules_swift] rules. The rules in this repository build the
-external Swift packages using [rules_swift] and native C/C++ rulesets making the Swift package
-products and targets available as Bazel targets.
+build, and consume Swift packages. The rules in this repository build the external Swift packages
+using [rules_swift] and native C/C++ rulesets making the Swift package products and targets
+available as Bazel targets.
 
 This repository is designed to fully replace [rules_spm] and provide utilities to ease Swift
 development inside a Bazel workspace.
@@ -29,9 +29,9 @@ development inside a Bazel workspace.
 
 ## Documentation
 
-- [High-level design](docs/design/high-level.md)
-- [Frequently Asked Questions](docs/faq.md)
-
+- [Rules and API documentation](/docs/README.md)
+- [High-level design](/docs/design/high-level.md)
+- [Frequently Asked Questions](/docs/faq.md)
 
 ## Prerequisites
 

docs/BUILD.bazel

@@ -1,6 +1,51 @@
+load(
+    "@cgrindel_bazel_starlib//bazeldoc:defs.bzl",
+    "doc_for_provs",
+    "write_header",
+    doc_providers = "providers",
+)
 load("@cgrindel_bazel_starlib//bzlformat:defs.bzl", "bzlformat_pkg")
 load("@cgrindel_bazel_starlib//markdown:defs.bzl", "markdown_pkg")
 
 bzlformat_pkg(name = "bzlformat")
 
 markdown_pkg(name = "markdown")
+
+# MARK: - Documentation Declarations
+
+_DOC_WITH_SYMBOLS = {
+    "repository_rules": [
+        "local_swift_package",
+        "swift_package",
+    ],
+}
+
+_ALL_DOC_PROVIDERS = [
+    doc_providers.create(
+        name = name + "_overview",
+        stardoc_input = "//swiftpkg:defs.bzl",
+        symbols = symbols,
+        deps = ["//swiftpkg:defs"],
+    )
+    for [
+        name,
+        symbols,
+    ] in _DOC_WITH_SYMBOLS.items()
+]
+
+# MARK: - Headers
+
+write_header(
+    name = "repository_rules_overview_header",
+    header_content = [
+        "# Repository Rules",
+        "",
+        """
+The rules described below are used to build Swift packages and make their 
+products and targets available as Bazel targets.
+""",
+    ],
+    symbols = _DOC_WITH_SYMBOLS["repository_rules"],
+)
+
+doc_for_provs(doc_provs = _ALL_DOC_PROVIDERS)

docs/README.md

@@ -0,0 +1,10 @@
+# Swift Bazel Documentation
+
+- For information on how configure and use Swift Bazel, check out the [quickstart] and the [tips
+  and tricks].
+- To view the Starlark API documentation, check out the [repository rules documentation].
+
+
+[quickstart]: /README.md#quickstart
+[repository rules documentation]: /doc/repository_rules_overview.md
+[tips and tricks]: /README.md#tips-and-tricks

docs/repository_rules_overview.md

@@ -0,0 +1,73 @@
+<!-- Generated with Stardoc, Do Not Edit! -->
+# Repository Rules
+
+
+The rules described below are used to build Swift packages and make their 
+products and targets available as Bazel targets.
+
+
+On this page:
+
+  * [local_swift_package](#local_swift_package)
+  * [swift_package](#swift_package)
+
+
+<a id="local_swift_package"></a>
+
+## local_swift_package
+
+<pre>
+local_swift_package(<a href="#local_swift_package-name">name</a>, <a href="#local_swift_package-env">env</a>, <a href="#local_swift_package-module_index">module_index</a>, <a href="#local_swift_package-path">path</a>, <a href="#local_swift_package-repo_mapping">repo_mapping</a>)
+</pre>
+
+Used to build a local Swift package.
+
+**ATTRIBUTES**
+
+
+| Name  | Description | Type | Mandatory | Default |
+| :------------- | :------------- | :------------- | :------------- | :------------- |
+| <a id="local_swift_package-name"></a>name |  A unique name for this repository.   | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required |  |
+| <a id="local_swift_package-env"></a>env |  Environment variables that will be passed to the execution environments for this repository rule. (e.g. SPM version check, SPM dependency resolution, SPM package description generation)   | <a href="https://bazel.build/rules/lib/dict">Dictionary: String -> String</a> | optional | <code>{}</code> |
+| <a id="local_swift_package-module_index"></a>module_index |  A JSON file that contains a mapping of Swift module names to Bazel targets that provide a module with that name.   | <a href="https://bazel.build/concepts/labels">Label</a> | required |  |
+| <a id="local_swift_package-path"></a>path |  The path to the local Swift package directory.   | String | required |  |
+| <a id="local_swift_package-repo_mapping"></a>repo_mapping |  A dictionary from local repository name to global repository name. This allows controls over workspace dependency resolution for dependencies of this repository.&lt;p&gt;For example, an entry <code>"@foo": "@bar"</code> declares that, for any time this repository depends on <code>@foo</code> (such as a dependency on <code>@foo//some:target</code>, it should actually resolve that dependency within globally-declared <code>@bar</code> (<code>@bar//some:target</code>).   | <a href="https://bazel.build/rules/lib/dict">Dictionary: String -> String</a> | required |  |
+
+
+<a id="swift_package"></a>
+
+## swift_package
+
+<pre>
+swift_package(<a href="#swift_package-name">name</a>, <a href="#swift_package-branch">branch</a>, <a href="#swift_package-commit">commit</a>, <a href="#swift_package-env">env</a>, <a href="#swift_package-init_submodules">init_submodules</a>, <a href="#swift_package-module_index">module_index</a>, <a href="#swift_package-patch_args">patch_args</a>, <a href="#swift_package-patch_cmds">patch_cmds</a>,
+              <a href="#swift_package-patch_cmds_win">patch_cmds_win</a>, <a href="#swift_package-patch_tool">patch_tool</a>, <a href="#swift_package-patches">patches</a>, <a href="#swift_package-recursive_init_submodules">recursive_init_submodules</a>, <a href="#swift_package-remote">remote</a>, <a href="#swift_package-repo_mapping">repo_mapping</a>,
+              <a href="#swift_package-shallow_since">shallow_since</a>, <a href="#swift_package-tag">tag</a>, <a href="#swift_package-verbose">verbose</a>)
+</pre>
+
+Used to download and build an external Swift package.
+
+
+**ATTRIBUTES**
+
+
+| Name  | Description | Type | Mandatory | Default |
+| :------------- | :------------- | :------------- | :------------- | :------------- |
+| <a id="swift_package-name"></a>name |  A unique name for this repository.   | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required |  |
+| <a id="swift_package-branch"></a>branch |  branch in the remote repository to checked out. Precisely one of branch, tag, or commit must be specified.   | String | optional | <code>""</code> |
+| <a id="swift_package-commit"></a>commit |  The commit or revision to download from version control.   | String | required |  |
+| <a id="swift_package-env"></a>env |  Environment variables that will be passed to the execution environments for this repository rule. (e.g. SPM version check, SPM dependency resolution, SPM package description generation)   | <a href="https://bazel.build/rules/lib/dict">Dictionary: String -> String</a> | optional | <code>{}</code> |
+| <a id="swift_package-init_submodules"></a>init_submodules |  Whether to clone submodules in the repository.   | Boolean | optional | <code>False</code> |
+| <a id="swift_package-module_index"></a>module_index |  A JSON file that contains a mapping of Swift module names to Bazel targets that provide a module with that name.   | <a href="https://bazel.build/concepts/labels">Label</a> | required |  |
+| <a id="swift_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, <code>patch</code> will be used.   | List of strings | optional | <code>["-p0"]</code> |
+| <a id="swift_package-patch_cmds"></a>patch_cmds |  Sequence of Bash commands to be applied on Linux/Macos after patches are applied.   | List of strings | optional | <code>[]</code> |
+| <a id="swift_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 | <code>[]</code> |
+| <a id="swift_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 | <code>""</code> |
+| <a id="swift_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 <code>patch_tool</code> attribute is specified or there are arguments other than <code>-p</code> in <code>patch_args</code> attribute.   | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | <code>[]</code> |
+| <a id="swift_package-recursive_init_submodules"></a>recursive_init_submodules |  Whether to clone submodules recursively in the repository.   | Boolean | optional | <code>False</code> |
+| <a id="swift_package-remote"></a>remote |  The version control location from where the repository should be downloaded.   | String | required |  |
+| <a id="swift_package-repo_mapping"></a>repo_mapping |  A dictionary from local repository name to global repository name. This allows controls over workspace dependency resolution for dependencies of this repository.&lt;p&gt;For example, an entry <code>"@foo": "@bar"</code> declares that, for any time this repository depends on <code>@foo</code> (such as a dependency on <code>@foo//some:target</code>, it should actually resolve that dependency within globally-declared <code>@bar</code> (<code>@bar//some:target</code>).   | <a href="https://bazel.build/rules/lib/dict">Dictionary: String -> String</a> | required |  |
+| <a id="swift_package-shallow_since"></a>shallow_since |  an optional date, not after the specified commit; the argument is not allowed if a tag is specified (which allows cloning with depth 1). Setting such a date close to the specified commit allows for a more shallow clone of the repository, saving bandwidth and wall-clock time.   | String | optional | <code>""</code> |
+| <a id="swift_package-tag"></a>tag |  tag in the remote repository to checked out. Precisely one of branch, tag, or commit must be specified.   | String | optional | <code>""</code> |
+| <a id="swift_package-verbose"></a>verbose |  -   | Boolean | optional | <code>False</code> |
+
+

swiftpkg/BUILD.bazel

@@ -1,11 +1,17 @@
 load("@bazel_skylib//:bzl_library.bzl", "bzl_library")
 load("@cgrindel_bazel_starlib//bzlformat:defs.bzl", "bzlformat_pkg")
 
+# Allow docs to access the defs.bzl
+package(default_visibility = ["//visibility:public"])
+
 bzl_library(
     name = "defs",
     srcs = ["defs.bzl"],
     visibility = ["//visibility:public"],
-    deps = ["//swiftpkg/internal:swift_package"],
+    deps = [
+        "//swiftpkg/internal:local_swift_package",
+        "//swiftpkg/internal:swift_package",
+    ],
 )
 
 bzlformat_pkg(name = "bzlformat")

swiftpkg/internal/BUILD.bazel

@@ -31,7 +31,10 @@ bzl_library(
     name = "pkginfos",
     srcs = ["pkginfos.bzl"],
     visibility = ["//swiftpkg:__subpackages__"],
-    deps = [":repository_utils"],
+    deps = [
+        ":repository_utils",
+        ":validations",
+    ],
 )
 
 bzl_library(
@@ -40,8 +43,11 @@ bzl_library(
     visibility = ["//swiftpkg:__subpackages__"],
     deps = [
         ":repository_files",
+        "//swiftpkg/internal/modulemap_parser:declarations",
+        "//swiftpkg/internal/modulemap_parser:parser",
         "@bazel_skylib//lib:paths",
         "@bazel_skylib//lib:sets",
+        "@cgrindel_bazel_starlib//bzllib:defs",
     ],
 )
 
@@ -95,8 +101,14 @@ bzl_library(
     srcs = ["swiftpkg_build_files.bzl"],
     visibility = ["//swiftpkg:__subpackages__"],
     deps = [
+        ":build_decls",
+        ":build_files",
+        ":clang_files",
+        ":load_statements",
+        ":pkginfo_target_deps",
         ":pkginfo_targets",
         ":pkginfos",
+        "@bazel_skylib//lib:paths",
         "@cgrindel_bazel_starlib//bzllib:defs",
     ],
 )
@@ -141,7 +153,11 @@ bzl_library(
     visibility = ["//swiftpkg:__subpackages__"],
     deps = [
         ":pkginfos",
+        ":repo_rules",
+        "@bazel_skylib//lib:dicts",
+        "@bazel_skylib//lib:paths",
         "@bazel_tools//tools/build_defs/repo:utils.bzl",
+        "@cgrindel_bazel_starlib//bzllib:defs",
     ],
 )
 

swiftpkg/internal/local_swift_package.bzl

@@ -80,5 +80,5 @@ _COMMON_ATTRS = dicts.add(
 local_swift_package = repository_rule(
     implementation = _local_swift_package_impl,
     attrs = _COMMON_ATTRS,
-    doc = "",
+    doc = "Used to build a local Swift package.",
 )

swiftpkg/internal/repo_rules.bzl

@@ -10,7 +10,10 @@ load(":swiftpkg_build_files.bzl", "swiftpkg_build_files")
 
 _swift_attrs = {
     "module_index": attr.label(
-        doc = "The JSON file that contains the module index by name.",
+        doc = """\
+A JSON file that contains a mapping of Swift module names to Bazel targets \
+that provide a module with that name.\
+""",
         mandatory = True,
     ),
 }

swiftpkg/internal/swift_package.bzl

@@ -158,5 +158,7 @@ _COMMON_ATTRS = dicts.add(
 swift_package = repository_rule(
     implementation = _swift_package_impl,
     attrs = _COMMON_ATTRS,
-    doc = "",
+    doc = """\
+Used to download and build an external Swift package.
+""",
 )