fix: fix deps and enable documentation generattion (#269)

Closes #143.

BUILD.bazel

@@ -38,7 +38,17 @@ tidy(
         # Run go_mod_tidy before go_update_repos
         ":go_mod_tidy",
         ":go_update_repos",
-        ":gazelle",
+        ":update_build_files",
+    ],
+)
+
+# This is meant to be fast and convenient to quickly update the source files
+# with the latest.
+tidy(
+    name = "update_files",
+    targets = [
+        ":update_all",
+        ":update_build_files",
     ],
 )
 
@@ -73,7 +83,7 @@ gazelle_binary(
 # gazelle:prefix github.com/cgrindel/swift_bazel
 # gazelle:go_naming_convention import
 gazelle(
-    name = "gazelle",
+    name = "update_build_files",
     command = "fix",
     gazelle = ":gazelle_bin",
 )

deps.bzl

@@ -27,13 +27,25 @@ def swift_bazel_dependencies():
         ],
     )
 
+    # GH143: Waiting for bazel-gazelle release with dep fix:
+    # https://github.com/bazelbuild/bazel-gazelle/pull/1413
+    # maybe(
+    #     http_archive,
+    #     name = "bazel_gazelle",
+    #     sha256 = "ecba0f04f96b4960a5b250c8e8eeec42281035970aa8852dda73098274d14a1d",
+    #     urls = [
+    #         "https://mirror.bazel.build/github.com/bazelbuild/bazel-gazelle/releases/download/v0.29.0/bazel-gazelle-v0.29.0.tar.gz",
+    #         "https://github.com/bazelbuild/bazel-gazelle/releases/download/v0.29.0/bazel-gazelle-v0.29.0.tar.gz",
+    #     ],
+    # )
+
     maybe(
         http_archive,
         name = "bazel_gazelle",
-        sha256 = "ecba0f04f96b4960a5b250c8e8eeec42281035970aa8852dda73098274d14a1d",
+        sha256 = "daa8c57c4a71485d4d0a3dd33605a2cc31a7dff5ceb5b2fa354eaa0e61ce9935",
+        strip_prefix = "bazel-gazelle-39aa39511f59223b242453d60e4e3f6f89ebf204",
         urls = [
-            "https://mirror.bazel.build/github.com/bazelbuild/bazel-gazelle/releases/download/v0.29.0/bazel-gazelle-v0.29.0.tar.gz",
-            "https://github.com/bazelbuild/bazel-gazelle/releases/download/v0.29.0/bazel-gazelle-v0.29.0.tar.gz",
+            "https://github.com/bazelbuild/bazel-gazelle/archive/39aa39511f59223b242453d60e4e3f6f89ebf204.tar.gz",
         ],
     )
 

docs/BUILD.bazel

@@ -1,69 +1,107 @@
+load("@bazel_skylib//:bzl_library.bzl", "bzl_library")
 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")
+load(":doc_infos.bzl", "doc_infos")
 
 bzlformat_pkg(name = "bzlformat")
 
 markdown_pkg(name = "markdown")
 
 # MARK: - Documentation Declarations
 
+_DOC_INFOS = [
+    doc_infos.new(
+        name = "internal_rules_and_macros",
+        label = "//swiftpkg:build_defs",
+        symbols = [
+            "generate_modulemap",
+            "resource_bundle_accessor",
+            "resource_bundle_infoplist",
+        ],
+    ),
+    doc_infos.new(
+        name = "repository_rules",
+        label = "//swiftpkg:defs",
+        symbols = [
+            "local_swift_package",
+            "swift_package",
+        ],
+    ),
+    doc_infos.new(
+        name = "rules_and_macros",
+        label = "//swiftpkg:defs",
+        symbols = [
+            "swift_update_packages",
+        ],
+    ),
+]
+
 _DOC_WITH_SYMBOLS = {
-    # GH143: Enable once bazel-gazelle deps are fixed.
-    # "macros": [
-    #     "swift_update_packages",
-    # ],
-    # "repository_rules": [
-    #     "local_swift_package",
-    #     "swift_package",
-    # ],
+    di.name: di
+    for di in _DOC_INFOS
 }
 
 _ALL_DOC_PROVIDERS = [
     doc_providers.create(
-        name = name + "_overview",
-        stardoc_input = "//swiftpkg:defs.bzl",
-        symbols = symbols,
-        deps = ["//swiftpkg:defs"],
+        name = di.name + "_overview",
+        stardoc_input = "{}.bzl".format(di.label),
+        symbols = di.symbols,
+        deps = [di.label],
     )
-    for [
-        name,
-        symbols,
-    ] in _DOC_WITH_SYMBOLS.items()
+    for di in _DOC_INFOS
 ]
 
 # MARK: - Headers
 
-# GH143: Enable once bazel-gazelle deps are fixed.
-# 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"],
-# )
+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"].symbols,
+)
+
+write_header(
+    name = "rules_and_macros_overview_header",
+    header_content = [
+        "# Rules and Macros",
+        "",
+        """
+The rules and macros described below are used to define Gazelle targets to aid \
+in the generation and maintenance of Swift package dependencies.
+""",
+    ],
+    symbols = _DOC_WITH_SYMBOLS["rules_and_macros"].symbols,
+)
 
-# GH143: Enable once bazel-gazelle deps are fixed.
-# write_header(
-#     name = "macros_overview_header",
-#     header_content = [
-#         "# Macros",
-#         "",
-#         """
-# The macros described below are used to define Gazelle targets to aid in the \
-# generation and maintenance of Swift package dependencies.
-# """,
-#     ],
-#     symbols = _DOC_WITH_SYMBOLS["macros"],
-# )
+write_header(
+    name = "internal_rules_and_macros_overview_header",
+    header_content = [
+        "# Internal Rules and Macros",
+        "",
+        """
+The rules and macros described below are used by `swift_bazel` to build the \
+external Swift packages.
+""",
+    ],
+    symbols = _DOC_WITH_SYMBOLS["internal_rules_and_macros"].symbols,
+)
 
 doc_for_provs(doc_provs = _ALL_DOC_PROVIDERS)
+
+bzl_library(
+    name = "doc_infos",
+    srcs = ["doc_infos.bzl"],
+    visibility = ["//visibility:public"],
+)

docs/README.md

@@ -2,9 +2,14 @@
 
 - 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].
+- To view the Starlark API documentation, check out the [repository rules documentation] and the
+  [rules and macros documentation].
+- If you are interested in learning more about the rules used to help build the external Swift
+  packages, check out the [internal rules and macros documentation].
 
 
 [quickstart]: /README.md#quickstart
 [repository rules documentation]: /docs/repository_rules_overview.md
+[rules and macros documentation]: /docs/rules_and_macros_overview.md
+[internal rules and macros documentation]: /docs/internal_rules_and_macros_overview.md
 [tips and tricks]: /README.md#tips-and-tricks

docs/doc_infos.bzl

@@ -0,0 +1,12 @@
+"""Module for organizing documentation."""
+
+def _new(name, label, symbols):
+    return struct(
+        name = name,
+        label = label,
+        symbols = symbols,
+    )
+
+doc_infos = struct(
+    new = _new,
+)

docs/internal_rules_and_macros_overview.md

@@ -0,0 +1,73 @@
+<!-- Generated with Stardoc, Do Not Edit! -->
+# Internal Rules and Macros
+
+
+The rules and macros described below are used by `swift_bazel` to build the external Swift packages.
+
+
+On this page:
+
+  * [generate_modulemap](#generate_modulemap)
+  * [resource_bundle_accessor](#resource_bundle_accessor)
+  * [resource_bundle_infoplist](#resource_bundle_infoplist)
+
+
+<a id="generate_modulemap"></a>
+
+## generate_modulemap
+
+<pre>
+generate_modulemap(<a href="#generate_modulemap-name">name</a>, <a href="#generate_modulemap-deps">deps</a>, <a href="#generate_modulemap-hdrs">hdrs</a>, <a href="#generate_modulemap-module_name">module_name</a>)
+</pre>
+
+Generate a modulemap for an Objective-C module.
+
+**ATTRIBUTES**
+
+
+| 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-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="resource_bundle_accessor"></a>
+
+## resource_bundle_accessor
+
+<pre>
+resource_bundle_accessor(<a href="#resource_bundle_accessor-name">name</a>, <a href="#resource_bundle_accessor-bundle_name">bundle_name</a>)
+</pre>
+
+Generate a Swift file with an SPM-specific `Bundle.module` accessor.
+
+**ATTRIBUTES**
+
+
+| Name  | Description | Type | Mandatory | Default |
+| :------------- | :------------- | :------------- | :------------- | :------------- |
+| <a id="resource_bundle_accessor-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_accessor-bundle_name"></a>bundle_name |  The name of the resource bundle.   | String | required |  |
+
+
+<a id="resource_bundle_infoplist"></a>
+
+## resource_bundle_infoplist
+
+<pre>
+resource_bundle_infoplist(<a href="#resource_bundle_infoplist-name">name</a>, <a href="#resource_bundle_infoplist-region">region</a>)
+</pre>
+
+Generate an Info.plist for an SPM resource bundle.
+
+**ATTRIBUTES**
+
+
+| 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> |
+
+

docs/repository_rules_overview.md

@@ -2,7 +2,7 @@
 # Repository Rules
 
 
-The rules described below are used to build Swift packages and make their 
+The rules described below are used to build Swift packages and make their
 products and targets available as Bazel targets.
 
 

docs/rules_and_macros_overview.md

@@ -0,0 +1,37 @@
+<!-- Generated with Stardoc, Do Not Edit! -->
+# Rules and Macros
+
+
+The rules and macros described below are used to define Gazelle targets to aid in the generation and maintenance of Swift package dependencies.
+
+
+On this page:
+
+  * [swift_update_packages](#swift_update_packages)
+
+
+<a id="swift_update_packages"></a>
+
+## swift_update_packages
+
+<pre>
+swift_update_packages(<a href="#swift_update_packages-name">name</a>, <a href="#swift_update_packages-gazelle">gazelle</a>, <a href="#swift_update_packages-package_manifest">package_manifest</a>, <a href="#swift_update_packages-swift_deps">swift_deps</a>, <a href="#swift_update_packages-swift_deps_fn">swift_deps_fn</a>, <a href="#swift_update_packages-swift_deps_index">swift_deps_index</a>,
+                      <a href="#swift_update_packages-kwargs">kwargs</a>)
+</pre>
+
+Defines gazelle update-repos targets that are used to resolve and update     Swift package dependencies.
+
+**PARAMETERS**
+
+
+| Name  | Description | Default Value |
+| :------------- | :------------- | :------------- |
+| <a id="swift_update_packages-name"></a>name |  The name of the <code>resolve</code> target as a <code>string</code>. The target name for the <code>update</code> target is derived from this value by appending <code>_to_latest</code>.   |  none |
+| <a id="swift_update_packages-gazelle"></a>gazelle |  The label to <code>gazelle_binary</code> that includes the <code>swift_bazel</code> Gazelle extension.   |  none |
+| <a id="swift_update_packages-package_manifest"></a>package_manifest |  Optional. The name of the Swift package manifest file as a <code>string</code>.   |  <code>"Package.swift"</code> |
+| <a id="swift_update_packages-swift_deps"></a>swift_deps |  Optional. The name of the Starlark file that should be updated with the Swift package dependencies as a <code>string</code>.   |  <code>"swift_deps.bzl"</code> |
+| <a id="swift_update_packages-swift_deps_fn"></a>swift_deps_fn |  Optional. The name of the Starlark function in the <code>swift_deps</code> file that should be updated with the Swift package dependencies as a <code>string</code>.   |  <code>"swift_dependencies"</code> |
+| <a id="swift_update_packages-swift_deps_index"></a>swift_deps_index |  Optional. The relative path to the Swift dependencies index JSON file. This path is relative to the repository root, not the location of this declaration.   |  <code>"swift_deps_index.json"</code> |
+| <a id="swift_update_packages-kwargs"></a>kwargs |  Attributes that are passed along to the gazelle declarations.   |  none |
+
+

swiftpkg/BUILD.bazel

@@ -31,5 +31,7 @@ bzl_library(
     visibility = ["//visibility:public"],
     deps = [
         "//swiftpkg/internal:generate_modulemap",
+        "//swiftpkg/internal:resource_bundle_accessor",
+        "//swiftpkg/internal:resource_bundle_infoplist",
     ],
 )