Add docs.

BUILD.bazel

@@ -0,0 +1,16 @@
+load("@bazel_skylib//:bzl_library.bzl", "bzl_library")
+
+exports_files(
+    ["defs.bzl"],
+    visibility = ["//docs:__pkg__"],
+)
+
+bzl_library(
+    name = "defs",
+    srcs = ["defs.bzl"],
+    visibility = ["//visibility:public"],
+    deps = [
+        "//ytt/private:ytt",
+        "//ytt:repositories",
+    ],
+)

README.md

@@ -18,12 +18,12 @@ http_archive(
 
 load("@rules_ytt//ytt:repositories.bzl",
   "rules_ytt_dependencies",
-  "ytt_register_toolchains",
+  "rules_ytt_register_toolchains",
 )
 
 rules_ytt_dependencies()
 
-ytt_register_toolchains()
+rules_ytt_register_toolchains()
 ```
 
 ## Usage

WORKSPACE

@@ -3,11 +3,22 @@ workspace(name = "rules_ytt")
 load("//ytt:repositories.bzl",
   "rules_ytt_dependencies",
   "rules_ytt_internal_dependencies",
-  "ytt_register_toolchains",
+  "rules_ytt_register_toolchains",
 )
 
 rules_ytt_dependencies()
 
 rules_ytt_internal_dependencies()
 
-ytt_register_toolchains()
+rules_ytt_register_toolchains()
+
+load("@aspect_bazel_lib//lib:repositories.bzl", "aspect_bazel_lib_dependencies", "aspect_bazel_lib_register_toolchains")
+
+aspect_bazel_lib_dependencies()
+
+aspect_bazel_lib_register_toolchains()
+
+load("@bazel_skylib//:workspace.bzl", "bazel_skylib_workspace")
+
+bazel_skylib_workspace()
+

docs/BUILD.bazel

@@ -0,0 +1,15 @@
+# This load statement must be in the docs/ package rather than anything users depend on
+# so that the dependency on stardoc doesn't leak to them.
+load("@aspect_bazel_lib//lib:docs.bzl", "stardoc_with_diff_test", "update_docs")
+
+stardoc_with_diff_test(
+    name = "ytt",
+    bzl_library_target = "//:defs",
+)
+
+stardoc_with_diff_test(
+    name = "repositories",
+    bzl_library_target = "//ytt:repositories",
+)
+
+update_docs(name = "update")

docs/repositories.md

@@ -0,0 +1,99 @@
+<!-- Generated with Stardoc: http://skydoc.bazel.build -->
+
+Declare runtime dependencies
+
+These are needed for local dev, and users must install them as well.
+See https://docs.bazel.build/versions/main/skylark/deploying.html#dependencies
+
+
+<a id="ytt_repositories"></a>
+
+## ytt_repositories
+
+<pre>
+ytt_repositories(<a href="#ytt_repositories-name">name</a>, <a href="#ytt_repositories-platform">platform</a>, <a href="#ytt_repositories-repo_mapping">repo_mapping</a>, <a href="#ytt_repositories-ytt_version">ytt_version</a>)
+</pre>
+
+Fetch external tools needed for ytt toolchain
+
+**ATTRIBUTES**
+
+
+| Name  | Description | Type | Mandatory | Default |
+| :------------- | :------------- | :------------- | :------------- | :------------- |
+| <a id="ytt_repositories-name"></a>name |  A unique name for this repository.   | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required |  |
+| <a id="ytt_repositories-platform"></a>platform |  -   | String | required |  |
+| <a id="ytt_repositories-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="ytt_repositories-ytt_version"></a>ytt_version |  -   | String | required |  |
+
+
+<a id="http_archive"></a>
+
+## http_archive
+
+<pre>
+http_archive(<a href="#http_archive-name">name</a>, <a href="#http_archive-kwargs">kwargs</a>)
+</pre>
+
+
+
+**PARAMETERS**
+
+
+| Name  | Description | Default Value |
+| :------------- | :------------- | :------------- |
+| <a id="http_archive-name"></a>name |  <p align="center"> - </p>   |  none |
+| <a id="http_archive-kwargs"></a>kwargs |  <p align="center"> - </p>   |  none |
+
+
+<a id="rules_ytt_dependencies"></a>
+
+## rules_ytt_dependencies
+
+<pre>
+rules_ytt_dependencies()
+</pre>
+
+rules_ytt runtime dependencies.
+
+
+
+<a id="rules_ytt_internal_dependencies"></a>
+
+## rules_ytt_internal_dependencies
+
+<pre>
+rules_ytt_internal_dependencies()
+</pre>
+
+rules_ytt dependencies for internal use only.
+
+
+
+<a id="rules_ytt_register_toolchains"></a>
+
+## rules_ytt_register_toolchains
+
+<pre>
+rules_ytt_register_toolchains(<a href="#rules_ytt_register_toolchains-name">name</a>, <a href="#rules_ytt_register_toolchains-version">version</a>, <a href="#rules_ytt_register_toolchains-kwargs">kwargs</a>)
+</pre>
+
+Convenience macro for users which does typical setup.
+
+- create a repository for each built-in platform like `ytt_linux_amd64` -
+  this repository is lazily fetched when node is needed for that platform.
+- create a repository exposing toolchains for each platform like `ytt_platforms`
+- register a toolchain pointing at each platform
+Users can avoid this macro and do these steps themselves, if they want more control.
+
+
+**PARAMETERS**
+
+
+| Name  | Description | Default Value |
+| :------------- | :------------- | :------------- |
+| <a id="rules_ytt_register_toolchains-name"></a>name |  base name for all created repos, like "ytt"   |  <code>"ytt"</code> |
+| <a id="rules_ytt_register_toolchains-version"></a>version |  Ytt tool version. Supported versions are listed in <code>ytt/private/versions.bzl</code>.   |  <code>"0.46.2"</code> |
+| <a id="rules_ytt_register_toolchains-kwargs"></a>kwargs |  passed to each node_repositories call   |  none |
+
+

docs/ytt.md

@@ -0,0 +1,24 @@
+<!-- Generated with Stardoc: http://skydoc.bazel.build -->
+
+
+
+<a id="ytt"></a>
+
+## ytt
+
+<pre>
+ytt(<a href="#ytt-name">name</a>, <a href="#ytt-image">image</a>, <a href="#ytt-srcs">srcs</a>)
+</pre>
+
+
+
+**ATTRIBUTES**
+
+
+| Name  | Description | Type | Mandatory | Default |
+| :------------- | :------------- | :------------- | :------------- | :------------- |
+| <a id="ytt-name"></a>name |  A unique name for this target.   | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required |  |
+| <a id="ytt-image"></a>image |  (DEPRECATED) Target that generates a Docker image. Used for extracting image digest.   | <a href="https://bazel.build/concepts/labels">Label</a> | optional | <code>None</code> |
+| <a id="ytt-srcs"></a>srcs |  List of files that will be passed to ytt with -f param.   | <a href="https://bazel.build/concepts/labels">List of labels</a> | required |  |
+
+

ytt/BUILD.bazel

@@ -1,4 +1,10 @@
 load("//ytt/private:resolved_toolchains.bzl", "resolved_toolchain")
+load("@bazel_skylib//:bzl_library.bzl", "bzl_library")
+
+exports_files(
+    ["repositories.bzl"],
+    visibility = ["//docs:__pkg__"],
+)
 
 # This is the target rule authors should put in their "toolchains"
 # attribute in order to get a runtime for the correct platform.
@@ -15,3 +21,15 @@ resolved_toolchain(
     tags = ["manual"],
     visibility = ["//visibility:public"],
 )
+
+bzl_library(
+    name = "repositories",
+    srcs = ["repositories.bzl"],
+    visibility = ["//:__subpackages__"],
+    deps = [
+        "//ytt/private:toolchains_repo",
+        "//ytt/private:versions",
+        "@bazel_tools//tools/build_defs/repo:http.bzl",
+        "@bazel_tools//tools/build_defs/repo:utils.bzl",
+    ],
+)

ytt/private/BUILD.bazel

@@ -0,0 +1,21 @@
+load("@bazel_skylib//:bzl_library.bzl", "bzl_library")
+
+bzl_library(
+    name = "ytt",
+    srcs = ["ytt.bzl"],
+    visibility = [
+        "//:__subpackages__",
+    ],
+)
+
+bzl_library(
+    name = "toolchains_repo",
+    srcs = ["toolchains_repo.bzl"],
+    visibility = ["//ytt:__subpackages__"],
+)
+
+bzl_library(
+    name = "versions",
+    srcs = ["versions.bzl"],
+    visibility = ["//ytt:__subpackages__"],
+)

ytt/private/toolchains_repo.bzl

@@ -50,7 +50,7 @@ def _toolchains_repo_impl(repository_ctx):
     build_content = """# Generated by toolchains_repo.bzl
 #
 # These can be registered in the workspace file or passed to --extra_toolchains flag.
-# By default all these toolchains are registered by the ytt_register_toolchains macro
+# By default all these toolchains are registered by the rules_ytt_register_toolchains macro
 # so you don't normally need to interact with these targets.
 
 """

ytt/repositories.bzl

@@ -20,10 +20,25 @@ def http_archive(name, **kwargs):
 # and released only in semver majors.
 # This is all fixed by bzlmod, so we just tolerate it for now.
 def rules_ytt_dependencies():
+    "rules_ytt runtime dependencies."
     pass
 
 def rules_ytt_internal_dependencies():
-    pass
+    "rules_ytt dependencies for internal use only."
+    http_archive(
+        name = "io_bazel_stardoc",
+        sha256 = "ec57139e466faae563f2fc39609da4948a479bb51b6d67aedd7d9b1b8059c433",
+        urls = [
+            "https://mirror.bazel.build/github.com/bazelbuild/stardoc/releases/download/0.5.4/stardoc-0.5.4.tar.gz",
+            "https://github.com/bazelbuild/stardoc/releases/download/0.5.4/stardoc-0.5.4.tar.gz",
+        ],
+    )
+    http_archive(
+        name = "aspect_bazel_lib",
+        sha256 = "c858cc637db5370f6fd752478d1153955b4b4cbec7ffe95eb4a47a48499a79c3",
+        strip_prefix = "bazel-lib-2.0.3",
+        url = "https://github.com/aspect-build/bazel-lib/releases/download/v2.0.3/bazel-lib-v2.0.3.tar.gz",
+    )
 
 ########
 # Remaining content of the file is only used to support toolchains.
@@ -71,18 +86,18 @@ ytt_repositories = repository_rule(
 )
 
 # Wrapper macro around everything above, this is the primary API
-def ytt_register_toolchains(name = "ytt", version = "0.46.2", register = True, **kwargs):
+def rules_ytt_register_toolchains(name = "ytt", version = "0.46.2", **kwargs):
     """Convenience macro for users which does typical setup.
 
-    - create a repository for each built-in platform like "ytt_linux_amd64" -
+    - create a repository for each built-in platform like `ytt_linux_amd64` -
       this repository is lazily fetched when node is needed for that platform.
-    - create a repository exposing toolchains for each platform like "ytt_platforms"
+    - create a repository exposing toolchains for each platform like `ytt_platforms`
     - register a toolchain pointing at each platform
     Users can avoid this macro and do these steps themselves, if they want more control.
+
     Args:
-        name: base name for all created repos, like "ytt1_14"
-        register: whether to call through to native.register_toolchains.
-            Should be True for WORKSPACE users, but false when used under bzlmod extension
+        name: base name for all created repos, like "ytt"
+        version: Ytt tool version. Supported versions are listed in `ytt/private/versions.bzl`.
         **kwargs: passed to each node_repositories call
     """
     for platform in PLATFORMS.keys():
@@ -92,8 +107,7 @@ def ytt_register_toolchains(name = "ytt", version = "0.46.2", register = True, *
             ytt_version = version,
             **kwargs
         )
-        if register:
-            native.register_toolchains("@%s_toolchains//:%s_toolchain" % (name, platform))
+        native.register_toolchains("@%s_toolchains//:%s_toolchain" % (name, platform))
 
     toolchains_repo(
         name = name + "_toolchains",