Merge pull request #65 from aiuto/docs

First cut at doc generation. They are ugly, but it's a start.

9 files changed, 217 insertions, 13 deletions

diff --git a/MODULE.bazel b/MODULE.bazel
index a7d09f7..114446a 100644
--- a/MODULE.bazel
+++ b/MODULE.bazel
@@ -13,3 +13,4 @@ module(
 
 # Only for development
 bazel_dep(name = "rules_pkg", version = "0.7.0", dev_dependency = True)
+bazel_dep(name = "stardoc", version = "0.5.3", dev_dependency = True)
diff --git a/README.md b/README.md
index 21acefd..463e0b2 100644
--- a/README.md
+++ b/README.md
@@ -18,6 +18,7 @@ WARNING: The code here is still in active initial development and will churn a l
 If you want to follow along:
 - Mailing list: [bazel-ssc@bazel.build](https://groups.google.com/a/bazel.build/g/bazel-ssc)  
 - Monthly eng meeting: [calendar link](MjAyMjA4MjJUMTYwMDAwWiBjXzUzcHBwZzFudWthZXRmb3E5NzhxaXViNmxzQGc&tmsrc=c_53pppg1nukaetfoq978qiub6ls%40group.calendar.google.com&scp=ALL)
+- [Latest docs](https://bazelbuild.github.io/rules_license/latest.md)
 
 Background reading:
 These is for learning about the problem space, and our approach to solutions. Concrete specifications will always appear in checked in code rather than documents.
diff --git a/WORKSPACE b/WORKSPACE
index 2d73352..654ea78 100644
--- a/WORKSPACE
+++ b/WORKSPACE
@@ -35,3 +35,16 @@ http_archive(
 load("@rules_pkg//:deps.bzl", "rules_pkg_dependencies")
 
 rules_pkg_dependencies()
+
+http_archive(
+    name = "io_bazel_stardoc",
+    sha256 = "3fd8fec4ddec3c670bd810904e2e33170bedfe12f90adf943508184be458c8bb",
+    urls = [
+        "https://mirror.bazel.build/github.com/bazelbuild/stardoc/releases/download/0.5.3/stardoc-0.5.3.tar.gz",
+        "https://github.com/bazelbuild/stardoc/releases/download/0.5.3/stardoc-0.5.3.tar.gz",
+    ],
+)
+
+load("@io_bazel_stardoc//:setup.bzl", "stardoc_repositories")
+
+stardoc_repositories()
diff --git a/docs/latest.md b/docs/latest.md
new file mode 100755
index 0000000..a7c373f
--- /dev/null
+++ b/docs/latest.md
@@ -0,0 +1,170 @@
+<!-- Generated with Stardoc: http://skydoc.bazel.build -->
+
+Rules for declaring the compliance licenses used by a package.
+
+
+
+<a id="license"></a>
+
+## license
+
+<pre>
+license(<a href="#license-name">name</a>, <a href="#license-copyright_notice">copyright_notice</a>, <a href="#license-license_kinds">license_kinds</a>, <a href="#license-license_text">license_text</a>, <a href="#license-namespace">namespace</a>, <a href="#license-package_name">package_name</a>, <a href="#license-package_url">package_url</a>,
+         <a href="#license-package_version">package_version</a>)
+</pre>
+
+
+
+**ATTRIBUTES**
+
+
+| Name  | Description | Type | Mandatory | Default |
+| :------------- | :------------- | :------------- | :------------- | :------------- |
+| <a id="license-name"></a>name |  A unique name for this target.   | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required |  |
+| <a id="license-copyright_notice"></a>copyright_notice |  Copyright notice.   | String | optional | <code>""</code> |
+| <a id="license-license_kinds"></a>license_kinds |  License kind(s) of this license. If multiple license kinds are listed in the LICENSE file, and they all apply, then all should be listed here. If the user can choose a single one of many, then only list one here.   | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | <code>[]</code> |
+| <a id="license-license_text"></a>license_text |  The license file.   | <a href="https://bazel.build/concepts/labels">Label</a> | optional | <code>LICENSE</code> |
+| <a id="license-namespace"></a>namespace |  A human readable name used to organize licenses into categories. This is used in google3 to differentiate third party licenses used for compliance versus internal licenses used by SLAsan for internal teams' SLAs.   | String | optional | <code>""</code> |
+| <a id="license-package_name"></a>package_name |  A human readable name identifying this package. This may be used to produce an index of OSS packages used by an applicatation.   | String | optional | <code>""</code> |
+| <a id="license-package_url"></a>package_url |  The URL this instance of the package was download from. This may be used to produce an index of OSS packages used by an applicatation.   | String | optional | <code>""</code> |
+| <a id="license-package_version"></a>package_version |  A human readable version string identifying this package. This may be used to produce an index of OSS packages used by an applicatation.  It should be a value that increases over time, rather than a commit hash.   | String | optional | <code>""</code> |
+
+
+
+<!-- Generated with Stardoc: http://skydoc.bazel.build -->
+
+Proof of concept. License restriction.
+
+<a id="license_kind"></a>
+
+## license_kind
+
+<pre>
+license_kind(<a href="#license_kind-name">name</a>, <a href="#license_kind-canonical_text">canonical_text</a>, <a href="#license_kind-conditions">conditions</a>, <a href="#license_kind-long_name">long_name</a>, <a href="#license_kind-url">url</a>)
+</pre>
+
+
+
+**ATTRIBUTES**
+
+
+| Name  | Description | Type | Mandatory | Default |
+| :------------- | :------------- | :------------- | :------------- | :------------- |
+| <a id="license_kind-name"></a>name |  A unique name for this target.   | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required |  |
+| <a id="license_kind-canonical_text"></a>canonical_text |  File containing the canonical text for this license. Must be UTF-8 encoded.   | <a href="https://bazel.build/concepts/labels">Label</a> | optional | <code>None</code> |
+| <a id="license_kind-conditions"></a>conditions |  Conditions to be met when using software under this license.  Conditions are defined by the organization using this license.   | List of strings | required |  |
+| <a id="license_kind-long_name"></a>long_name |  Human readable long name of license.   | String | optional | <code>""</code> |
+| <a id="license_kind-url"></a>url |  URL pointing to canonical license definition   | String | optional | <code>""</code> |
+
+
+
+<!-- Generated with Stardoc: http://skydoc.bazel.build -->
+
+Rules for declaring metadata about a package.
+
+<a id="package_info"></a>
+
+## package_info
+
+<pre>
+package_info(<a href="#package_info-name">name</a>, <a href="#package_info-package_name">package_name</a>, <a href="#package_info-package_url">package_url</a>, <a href="#package_info-package_version">package_version</a>)
+</pre>
+
+
+
+**ATTRIBUTES**
+
+
+| Name  | Description | Type | Mandatory | Default |
+| :------------- | :------------- | :------------- | :------------- | :------------- |
+| <a id="package_info-name"></a>name |  A unique name for this target.   | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required |  |
+| <a id="package_info-package_name"></a>package_name |  A human readable name identifying this package. This may be used to produce an index of OSS packages used by an applicatation.   | String | optional | <code>""</code> |
+| <a id="package_info-package_url"></a>package_url |  The URL this instance of the package was download from. This may be used to produce an index of OSS packages used by an applicatation.   | String | optional | <code>""</code> |
+| <a id="package_info-package_version"></a>package_version |  A human readable version string identifying this package. This may be used to produce an index of OSS packages used by an applicatation.  It should be a value that increases over time, rather than a commit hash.   | String | optional | <code>""</code> |
+
+
+
+<!-- Generated with Stardoc: http://skydoc.bazel.build -->
+
+Providers for license rules.
+
+<a id="LicenseInfo"></a>
+
+## LicenseInfo
+
+<pre>
+LicenseInfo(<a href="#LicenseInfo-copyright_notice">copyright_notice</a>, <a href="#LicenseInfo-label">label</a>, <a href="#LicenseInfo-license_kinds">license_kinds</a>, <a href="#LicenseInfo-license_text">license_text</a>, <a href="#LicenseInfo-namespace">namespace</a>, <a href="#LicenseInfo-package_name">package_name</a>,
+            <a href="#LicenseInfo-package_url">package_url</a>, <a href="#LicenseInfo-package_version">package_version</a>)
+</pre>
+
+Provides information about a license instance.
+
+**FIELDS**
+
+
+| Name  | Description |
+| :------------- | :------------- |
+| <a id="LicenseInfo-copyright_notice"></a>copyright_notice |  string: Human readable short copyright notice    |
+| <a id="LicenseInfo-label"></a>label |  Label: label of the license rule    |
+| <a id="LicenseInfo-license_kinds"></a>license_kinds |  list(LicenseKindInfo): License kinds    |
+| <a id="LicenseInfo-license_text"></a>license_text |  string: The license file path    |
+| <a id="LicenseInfo-namespace"></a>namespace |  string: namespace of the license rule    |
+| <a id="LicenseInfo-package_name"></a>package_name |  string: Human readable package name    |
+| <a id="LicenseInfo-package_url"></a>package_url |  URL from which this package was downloaded.    |
+| <a id="LicenseInfo-package_version"></a>package_version |  Human readable version string    |
+
+
+
+<!-- Generated with Stardoc: http://skydoc.bazel.build -->
+
+Providers for license rules.
+
+<a id="LicenseKindInfo"></a>
+
+## LicenseKindInfo
+
+<pre>
+LicenseKindInfo(<a href="#LicenseKindInfo-conditions">conditions</a>, <a href="#LicenseKindInfo-label">label</a>, <a href="#LicenseKindInfo-long_name">long_name</a>, <a href="#LicenseKindInfo-name">name</a>)
+</pre>
+
+Provides information about a license_kind instance.
+
+**FIELDS**
+
+
+| Name  | Description |
+| :------------- | :------------- |
+| <a id="LicenseKindInfo-conditions"></a>conditions |  list(string): List of conditions to be met when using this packages under this license.    |
+| <a id="LicenseKindInfo-label"></a>label |  Label: The full path to the license kind definition.    |
+| <a id="LicenseKindInfo-long_name"></a>long_name |  string: Human readable license name    |
+| <a id="LicenseKindInfo-name"></a>name |  string: Canonical license name    |
+
+
+
+<!-- Generated with Stardoc: http://skydoc.bazel.build -->
+
+Providers for license rules.
+
+<a id="PackageInfo"></a>
+
+## PackageInfo
+
+<pre>
+PackageInfo(<a href="#PackageInfo-type">type</a>, <a href="#PackageInfo-label">label</a>, <a href="#PackageInfo-package_name">package_name</a>, <a href="#PackageInfo-package_url">package_url</a>, <a href="#PackageInfo-package_version">package_version</a>)
+</pre>
+
+Provides information about a package.
+
+**FIELDS**
+
+
+| Name  | Description |
+| :------------- | :------------- |
+| <a id="PackageInfo-type"></a>type |  string: How to interpret data    |
+| <a id="PackageInfo-label"></a>label |  Label: label of the package_info rule    |
+| <a id="PackageInfo-package_name"></a>package_name |  string: Human readable package name    |
+| <a id="PackageInfo-package_url"></a>package_url |  string: URL from which this package was downloaded.    |
+| <a id="PackageInfo-package_version"></a>package_version |  string: Human readable version string    |
+
+
+
diff --git a/rules/BUILD b/rules/BUILD
index 1d67059..83e8c14 100644
--- a/rules/BUILD
+++ b/rules/BUILD
@@ -37,3 +37,12 @@ filegroup(
     name = "standard_package",
     srcs = glob(["**"]),
 )
+
+# Do not create a bzl_library(). That would create a dependency loop back
+# to bazel-skylib. We export the .bzl files to the documentation maker.
+exports_files(
+    glob([
+        "*.bzl",
+    ]),
+    visibility = ["//doc_build:__pkg__"],
+)
diff --git a/rules/license.bzl b/rules/license.bzl
index 183e106..e461388 100644
--- a/rules/license.bzl
+++ b/rules/license.bzl
@@ -13,7 +13,6 @@
 # limitations under the License.
 """Rules for declaring the compliance licenses used by a package.
 
-See: go/license-checking-v2
 """
 
 load(
@@ -74,7 +73,6 @@ _license = rule(
 def license(
         name,
         license_text = "LICENSE",
-        visibility = ["//visibility:public"],
         license_kind = None,
         license_kinds = None,
         copyright_notice = None,
@@ -82,21 +80,27 @@ def license(
         package_url = None,
         package_version = None,
         namespace = "compliance",
-        tags = []):
+        tags = [],
+        visibility = ["//visibility:public"]):
     """Wrapper for license rule.
 
+    @wraps(_license)
+
     Args:
       name: str target name.
       license_text: str Filename of the license file
-      visibility: list(label) visibility spec
       license_kind: label a single license_kind. Only one of license_kind or license_kinds may
                     be specified
       license_kinds: list(label) list of license_kind targets.
       copyright_notice: str Copyright notice associated with this package.
-      package_name : str A human readable name identifying this package. This
-                     may be used to produce an index of OSS packages used by
-                     an application.
+      package_name: str A human readable name identifying this package. This
+                    may be used to produce an index of OSS packages used by
+                    an application.
+      package_url: str The canonical URL this package was downloaded from.
+      package_version: str The version corresponding the the URL.
+      namespace: str Undocumened. Internal.
       tags: list(str) tags applied to the rule
+      visibility: list(label) visibility spec.
     """
     if license_kind:
         if license_kinds:
@@ -109,7 +113,6 @@ def license(
     if len(srcs) != 1 or srcs[0] != license_text:
         fail("Specified license file doesn't exist: %s" % license_text)
 
-
     _license(
         name = name,
         license_kinds = license_kinds,
diff --git a/rules/license_impl.bzl b/rules/license_impl.bzl
index c506953..457af13 100644
--- a/rules/license_impl.bzl
+++ b/rules/license_impl.bzl
@@ -13,7 +13,6 @@
 # limitations under the License.
 """Rules for declaring the licenses used by a package.
 
-See: go/license-checking-v2
 """
 
 load(
diff --git a/rules/license_kind.bzl b/rules/license_kind.bzl
index 5c8022e..7e6c024 100644
--- a/rules/license_kind.bzl
+++ b/rules/license_kind.bzl
@@ -52,6 +52,10 @@ _license_kind = rule(
 )
 
 def license_kind(name, **kwargs):
+    """Wrapper for license_kind.
+
+    @wraps(_license_kind)
+    """
     if "conditions" not in kwargs:
         kwargs["conditions"] = []
     if "long_name" not in kwargs:
diff --git a/rules/package_info.bzl b/rules/package_info.bzl
index a8643f8..c0bef0b 100644
--- a/rules/package_info.bzl
+++ b/rules/package_info.bzl
@@ -75,19 +75,23 @@ def package_info(
         package_name = None,
         package_url = None,
         package_version = None,
-        visibility = ["//visibility:public"]):
+        **kwargs):
     """Wrapper for package_info rule.
 
+    @wraps(_package_info)
+
     Args:
       name: str target name.
-      package_name : str A human readable name identifying this package. This
-                     may be used to produce an index of OSS packages used by
-                     an application.
+      package_name: str A human readable name identifying this package. This
+                    may be used to produce an index of OSS packages used by
+                    an application.
       package_url: str The canoncial URL this package distribution was retrieved from.
                        Note that, because of local mirroring, that might not be the 
                        physical URL it was retrieved from.
       package_version: str A human readable name identifying version of this package.
+      kwargs: other args. Most are ignored.
     """
+    visibility = kwargs.get("visibility") or ["//visibility:public"]
     _package_info(
         name = name,
         package_name = package_name,