diff options
author | Tony Aiuto <aiuto@google.com> | 2022-12-15 13:39:19 -0500 |
---|---|---|
committer | Tony Aiuto <aiuto@google.com> | 2022-12-15 13:39:19 -0500 |
commit | b96be504bcaf97e59e3fc5ed1c0dec291bc0c315 (patch) | |
tree | 4cbe9ca591e43c8483dc606608f08a5856d46ff2 | |
parent | 183581b9c3844a661e97bbc7979e947dee6e2c30 (diff) | |
download | bazelbuild-rules_license-b96be504bcaf97e59e3fc5ed1c0dec291bc0c315.tar.gz |
first cut at doc generation
-rw-r--r-- | MODULE.bazel | 1 | ||||
-rw-r--r-- | WORKSPACE | 13 | ||||
-rwxr-xr-x | docs/latest.md | 179 | ||||
-rw-r--r-- | rules/BUILD | 9 | ||||
-rw-r--r-- | rules/license.bzl | 18 | ||||
-rw-r--r-- | rules/license_kind.bzl | 4 | ||||
-rw-r--r-- | rules/package_info.bzl | 10 | ||||
-rw-r--r-- | version.bzl | 2 |
8 files changed, 224 insertions, 12 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) @@ -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..a748763 --- /dev/null +++ b/docs/latest.md @@ -0,0 +1,179 @@ +<!-- Generated with Stardoc: http://skydoc.bazel.build --> + +Rules for declaring the compliance licenses used by a package. + +See: go/license-checking-v2 + + +<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 the compliance licenses used by a package. + +See: go/license-checking-v2 + + + +<!-- 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..b201625 100644 --- a/rules/license.bzl +++ b/rules/license.bzl @@ -74,7 +74,6 @@ _license = rule( def license( name, license_text = "LICENSE", - visibility = ["//visibility:public"], license_kind = None, license_kinds = None, copyright_notice = None, @@ -82,21 +81,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 +114,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_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..ee325ae 100644 --- a/rules/package_info.bzl +++ b/rules/package_info.bzl @@ -75,19 +75,21 @@ def package_info( package_name = None, package_url = None, package_version = None, - visibility = ["//visibility:public"]): + **kwargs): """Wrapper for package_info rule. 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, diff --git a/version.bzl b/version.bzl index 0acecb6..f732579 100644 --- a/version.bzl +++ b/version.bzl @@ -13,4 +13,4 @@ # limitations under the License. """The version of rules_license.""" -version = "0.0.4" +version = "0.0.5" |