Organized release-related code under bzlrelease (#45)

Moved release-related macros under bzlrelease.
Migrated code from cgrindel/bazel-doc to this repo. It now lives under bazeldoc. This migration was planned. It happened now so that a change to doc_for_provs could be added to support documentation in different directories.
Added release package and moved this repository's release declarations there. Also, moved the snippets template.

BUILD.bazel

@@ -7,10 +7,6 @@ load(
     "@cgrindel_rules_updatesrc//updatesrc:updatesrc.bzl",
     "updatesrc_update_all",
 )
-load("@rules_pkg//:pkg.bzl", "pkg_tar")
-load("//rules:generate_release_notes.bzl", "generate_release_notes")
-load("//rules:generate_workspace_snippet.bzl", "generate_workspace_snippet")
-load("//rules:update_readme.bzl", "update_readme")
 
 bzlformat_pkg(name = "bzlformat")
 
@@ -21,6 +17,8 @@ bzlformat_missing_pkgs(
 updatesrc_update_all(
     name = "update_all",
     targets_to_run = [
+        "//doc/bazeldoc:update",
+        "//doc/bzlrelease:update",
         "//doc:update",
         ":bzlformat_missing_pkgs_fix",
     ],
@@ -35,29 +33,12 @@ test_suite(
         "manual",
     ],
     tests = [
+        "//tests/bzlrelease_tests/rules_tests/generate_release_notes_tests:integration_tests",
+        "//tests/bzlrelease_tests/rules_tests/generate_workspace_snippet_tests:integration_tests",
+        "//tests/bzlrelease_tests/rules_tests/update_readme_tests:integration_tests",
         "//tests/lib_tests/private_tests/git_tests:integration_tests",
         "//tests/lib_tests/private_tests/github_tests:integration_tests",
-        "//tests/rules_tests/generate_release_notes_tests:integration_tests",
-        "//tests/rules_tests/generate_workspace_snippet_tests:integration_tests",
-        "//tests/rules_tests/update_readme_tests:integration_tests",
         "//tests/tools_tests:integration_tests",
     ],
     visibility = ["//:__subpackages__"],
 )
-
-# MARK: - Release
-
-generate_workspace_snippet(
-    name = "generate_workspace_snippet",
-    template = "workspace_snippet.tmpl",
-)
-
-generate_release_notes(
-    name = "generate_release_notes",
-    generate_workspace_snippet = ":generate_workspace_snippet",
-)
-
-update_readme(
-    name = "update_readme",
-    generate_workspace_snippet = ":generate_workspace_snippet",
-)

README.md

@@ -40,3 +40,7 @@ load("@io_bazel_stardoc//:setup.bzl", "stardoc_repositories")
 stardoc_repositories()
 ```
 <!-- END WORKSPACE SNIPPET -->
+
+## Other Documentation
+
+- [Release Process](release/README.md)

WORKSPACE

@@ -8,10 +8,6 @@ load("@bazel_skylib//:workspace.bzl", "bazel_skylib_workspace")
 
 bazel_skylib_workspace()
 
-load("@cgrindel_bazel_doc//bazeldoc:deps.bzl", "bazeldoc_dependencies")
-
-bazeldoc_dependencies()
-
 load("@io_bazel_stardoc//:setup.bzl", "stardoc_repositories")
 
 stardoc_repositories()
@@ -40,9 +36,3 @@ gazelle_dependencies()
 load("@com_google_protobuf//:protobuf_deps.bzl", "protobuf_deps")
 
 protobuf_deps()
-
-# MARK: - Release Deps
-
-load("@rules_pkg//:deps.bzl", "rules_pkg_dependencies")
-
-rules_pkg_dependencies()

bazeldoc/BUILD.bazel

@@ -0,0 +1,17 @@
+load("@cgrindel_rules_bzlformat//bzlformat:bzlformat.bzl", "bzlformat_pkg")
+load("@bazel_skylib//:bzl_library.bzl", "bzl_library")
+
+package(default_visibility = ["//visibility:public"])
+
+bzlformat_pkg(name = "bzlformat")
+
+bzl_library(
+    name = "defs",
+    srcs = ["defs.bzl"],
+    deps = [
+        "//bazeldoc/private:doc_for_provs",
+        "//bazeldoc/private:providers",
+        "//bazeldoc/private:write_file_list",
+        "//bazeldoc/private:write_header",
+    ],
+)

bazeldoc/defs.bzl

@@ -0,0 +1,12 @@
+load("//bazeldoc/private:doc_for_provs.bzl", _doc_for_provs = "doc_for_provs")
+load("//bazeldoc/private:write_header.bzl", _write_header = "write_header")
+load("//bazeldoc/private:providers.bzl", _providers = "providers")
+load("//bazeldoc/private:write_file_list.bzl", _write_file_list = "write_file_list")
+
+# Rules and Macros
+doc_for_provs = _doc_for_provs
+write_header = _write_header
+write_file_list = _write_file_list
+
+# API
+providers = _providers

bazeldoc/private/BUILD.bazel

@@ -0,0 +1,76 @@
+load("@cgrindel_rules_bzlformat//bzlformat:bzlformat.bzl", "bzlformat_pkg")
+load("@bazel_skylib//:bzl_library.bzl", "bzl_library")
+
+package(default_visibility = ["//bazeldoc:__subpackages__"])
+
+bzlformat_pkg(name = "bzlformat")
+
+bzl_library(
+    name = "diff_test_for_provs",
+    srcs = ["diff_test_for_provs.bzl"],
+    deps = [
+        "@bazel_skylib//rules:diff_test",
+    ],
+)
+
+bzl_library(
+    name = "doc_for_provs",
+    srcs = ["doc_for_provs.bzl"],
+    deps = [
+        ":diff_test_for_provs",
+        ":stardoc_for_prov",
+        ":update_doc",
+    ],
+)
+
+bzl_library(
+    name = "doc_utilities",
+    srcs = ["doc_utilities.bzl"],
+)
+
+bzl_library(
+    name = "providers",
+    srcs = ["providers.bzl"],
+)
+
+bzl_library(
+    name = "stardoc_for_prov",
+    srcs = ["stardoc_for_prov.bzl"],
+    deps = [
+        "@io_bazel_stardoc//stardoc:stardoc_lib",
+    ],
+)
+
+bzl_library(
+    name = "update_doc",
+    srcs = ["update_doc.bzl"],
+    deps = [
+        "@bazel_skylib//rules:write_file",
+    ],
+)
+
+bzl_library(
+    name = "write_doc",
+    srcs = ["write_doc.bzl"],
+    deps = [
+        "@bazel_skylib//rules:write_file",
+    ],
+)
+
+bzl_library(
+    name = "write_file_list",
+    srcs = ["write_file_list.bzl"],
+    deps = [
+        ":doc_utilities",
+        ":write_doc",
+    ],
+)
+
+bzl_library(
+    name = "write_header",
+    srcs = ["write_header.bzl"],
+    deps = [
+        ":doc_utilities",
+        ":write_doc",
+    ],
+)

bazeldoc/private/diff_test_for_provs.bzl

@@ -0,0 +1,33 @@
+load("@bazel_skylib//rules:diff_test.bzl", "diff_test")
+
+def diff_test_for_prov(doc_prov):
+    """Defines a `diff_test` for a document provider.
+
+    Args:
+        doc_prov: A `struct` as returned from `providers.create()`.
+
+    Returns:
+        None.
+    """
+    diff_test(
+        name = "test_" + doc_prov.name,
+        file1 = doc_prov.out_basename,
+        file2 = doc_prov.doc_basename,
+    )
+
+def diff_test_for_provs(doc_provs):
+    """Defines a `diff_test` for each of the provided document providers.
+
+    Args:
+        doc_provs: A `list` of document provider `struct` values as returned
+                   from `providers.create()`.
+
+    Returns:
+        None.
+    """
+    [
+        diff_test_for_prov(
+            doc_prov = doc_prov,
+        )
+        for doc_prov in doc_provs
+    ]

bazeldoc/private/doc_for_provs.bzl

@@ -0,0 +1,17 @@
+load(":stardoc_for_prov.bzl", "stardoc_for_provs")
+load(":diff_test_for_provs.bzl", "diff_test_for_provs")
+load(":update_doc.bzl", "update_doc")
+
+def doc_for_provs(doc_provs, doc_path = "doc"):
+    """Defines targets for generating documentation, testing that the generated doc matches the workspace directory, and copying the generated doc to the workspace directory.
+
+    Args:
+        doc_provs: A `list` of document provider `struct` values as returned
+                   from `providers.create()`.
+
+    Returns:
+        None.
+    """
+    stardoc_for_provs(doc_provs = doc_provs)
+    diff_test_for_provs(doc_provs = doc_provs)
+    update_doc(doc_provs = doc_provs, doc_path = doc_path)

bazeldoc/private/doc_utilities.bzl

@@ -0,0 +1,32 @@
+"""Defines utility functions for working with markdown documentation files."""
+
+def _link(label, url):
+    """Creates a markdown link.
+
+    Args:
+        label: The label for the link as a `string`.
+        url: The URL for the link as a `string`.
+
+    Returns:
+        A markdown link as a `string`.
+    """
+    return "[{label}]({url})".format(
+        label = label,
+        url = url,
+    )
+
+def _toc_entry(label, url):
+    """Creates table-of-contents (TOC) entry suitable for markdown documents.
+
+    Args:
+        label: The label for the link as a `string`.
+        url: The URL for the link as a `string`.
+
+    Returns:
+    """
+    return "  * " + _link(label, url)
+
+doc_utilities = struct(
+    link = _link,
+    toc_entry = _toc_entry,
+)

bazeldoc/private/providers.bzl

@@ -0,0 +1,66 @@
+"""Defines functions for creating document provider `struct` values."""
+
+def _create(
+        name,
+        stardoc_input,
+        deps,
+        doc_label = None,
+        out_basename = None,
+        doc_basename = None,
+        header_label = None,
+        header_basename = None,
+        symbols = None,
+        is_stardoc = True):
+    """Create a documentation provider.
+
+    Args:
+        name: A `string` which identifies the doc output. If no `symbols`
+              are provided, all of the symbols which are defined in the
+              corresponding `.bzl` file are documented.
+        stardoc_input: A `string` representing the input label provided to the
+               `stardoc` declaration.
+        deps: A `list` of deps for the stardoc rule.
+        doc_label: Optional. A `string` which is the doc label name.
+        out_basename: Optional. A `string` which is the basename for the
+                      output file.
+        doc_basename: Optional. A `string` which is the basename for the
+                      final documentation file.
+        header_label: Optional. A `string` which is the header label name,
+                      if the header is being generated.
+        header_basename: Optional. The basename (`string`) of the header
+                        filename file, if one is being used.
+        symbols: Optional. A `list` of symbol names that should be included
+                 in the documentation.
+        is_stardoc: A `bool` indicating whether a `stardoc` declaration should
+                    be created.
+
+    Returns:
+      A `struct` representing a documentation provider.
+    """
+    if doc_label == None:
+        doc_label = name + "_doc"
+    if out_basename == None:
+        out_basename = name + ".md_"
+    if doc_basename == None:
+        doc_basename = name + ".md"
+    if header_label == None:
+        header_label = name + "_header"
+    if header_basename == None:
+        header_basename = header_label + ".vm"
+
+    return struct(
+        name = name,
+        stardoc_input = stardoc_input,
+        deps = deps,
+        doc_label = doc_label,
+        out_basename = out_basename,
+        doc_basename = doc_basename,
+        header_label = header_label,
+        header_basename = header_basename,
+        symbols = symbols,
+        is_stardoc = is_stardoc,
+    )
+
+providers = struct(
+    create = _create,
+)

bazeldoc/private/stardoc_for_prov.bzl

@@ -0,0 +1,37 @@
+load("@io_bazel_stardoc//stardoc:stardoc.bzl", "stardoc")
+
+def stardoc_for_prov(doc_prov):
+    """Defines a `stardoc` target for a document provider.
+
+    Args:
+        doc_prov: A `struct` as returned from `providers.create()`.
+
+    Returns:
+        None.
+    """
+    stardoc(
+        name = doc_prov.name,
+        out = doc_prov.out_basename,
+        header_template = doc_prov.header_basename,
+        input = doc_prov.stardoc_input,
+        symbol_names = doc_prov.symbols,
+        deps = doc_prov.deps,
+    )
+
+def stardoc_for_provs(doc_provs):
+    """Defines a `stardoc` for each of the provided document providers.
+
+    Args:
+        doc_provs: A `list` of document provider `struct` values as returned
+                   from `providers.create()`.
+
+    Returns:
+        None.
+    """
+    [
+        stardoc_for_prov(
+            doc_prov = doc_prov,
+        )
+        for doc_prov in doc_provs
+        if doc_prov.is_stardoc
+    ]