Merge pull request #1 from cgrindel/initial_files

Initial files copied from rules_spm.

.bazelrc

@@ -0,0 +1,8 @@
+# Import Shared settings
+import %workspace%/shared.bazelrc
+
+# Import CI settings.
+import %workspace%/ci.bazelrc
+
+# Try to import a local.rc file; typically, written by CI
+try-import %workspace%/local.bazelrc

.github/workflows/bazel.yml

@@ -0,0 +1,36 @@
+name: Build
+
+on:
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  macos_build:
+
+    runs-on: macos-11.0
+
+    steps:
+    - uses: actions/checkout@v2
+
+    - name: Write local.bazelrc File
+      shell: bash
+      run: |
+        cat >local.bazelrc <<EOF
+        common --config=ci
+        EOF
+
+    - name: Output the Bazel Info
+      shell: bash
+      run: |
+        bazelisk info
+
+    - name: Execute Tests
+      shell: bash
+      run: |
+        bazelisk test //... 
+
+    - name: Build Anything Not Tested
+      shell: bash
+      run: |
+        bazelisk build //... 
+

.gitignore

@@ -0,0 +1,3 @@
+# Ignore Bazel symlinks
+bazel-*
+

README.md

@@ -1,2 +1,15 @@
-# bazel-doc
-Helpers for generating Starlark documentation using stardoc.
+# Macros for Generating Starlark Documentation
+
+This repository contains macros and APIs that reduce some of the boilerplate when generating
+documentation for Starlark code.
+
+## Reference Documentation
+
+[Click here](/doc) for reference documentation for the rules and other definitions in this
+repository.
+
+## Quickstart
+
+Look at the [BUILD.bazel](/doc/BUILD.bazel) in the documentation directory for this repository. It
+uses the macros and APIs defined in this repository.
+

WORKSPACE

@@ -0,0 +1,13 @@
+workspace(name = "cgrindel_bazel_doc")
+
+load("//bazeldoc:deps.bzl", "bazeldoc_dependencies")
+
+bazeldoc_dependencies()
+
+load("@bazel_skylib//:workspace.bzl", "bazel_skylib_workspace")
+
+bazel_skylib_workspace()
+
+load("@io_bazel_stardoc//:setup.bzl", "stardoc_repositories")
+
+stardoc_repositories()

bazeldoc/BUILD.bazel

@@ -0,0 +1,18 @@
+load("@bazel_skylib//:bzl_library.bzl", "bzl_library")
+
+package(default_visibility = ["//visibility:public"])
+
+# NOTE: We cannot create a bzl_library for deps.bzl because it references @bazel_tools.
+# Issue: https://github.com/bazelbuild/bazel-skylib/issues/127
+exports_files(["deps.bzl"])
+
+bzl_library(
+    name = "bazeldoc",
+    srcs = ["bazeldoc.bzl"],
+    deps = [
+        "//bazeldoc/internal:doc_for_provs",
+        "//bazeldoc/internal:providers",
+        "//bazeldoc/internal:write_file_list",
+        "//bazeldoc/internal:write_header",
+    ],
+)

bazeldoc/bazeldoc.bzl

@@ -0,0 +1,12 @@
+load("//bazeldoc/internal:doc_for_provs.bzl", _doc_for_provs = "doc_for_provs")
+load("//bazeldoc/internal:write_header.bzl", _write_header = "write_header")
+load("//bazeldoc/internal:providers.bzl", _providers = "providers")
+load("//bazeldoc/internal: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/deps.bzl

@@ -0,0 +1,24 @@
+load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
+load("@bazel_tools//tools/build_defs/repo:utils.bzl", "maybe")
+
+def bazeldoc_dependencies():
+    """Loads the dependencies for bazeldoc."""
+    maybe(
+        http_archive,
+        name = "bazel_skylib",
+        urls = [
+            "https://github.com/bazelbuild/bazel-skylib/releases/download/1.1.1/bazel-skylib-1.1.1.tar.gz",
+            "https://mirror.bazel.build/github.com/bazelbuild/bazel-skylib/releases/download/1.1.1/bazel-skylib-1.1.1.tar.gz",
+        ],
+        sha256 = "c6966ec828da198c5d9adbaa94c05e3a1c7f21bd012a0b29ba8ddbccb2c93b0d",
+    )
+
+    maybe(
+        http_archive,
+        name = "io_bazel_stardoc",
+        sha256 = "c9794dcc8026a30ff67cf7cf91ebe245ca294b20b071845d12c192afe243ad72",
+        urls = [
+            "https://mirror.bazel.build/github.com/bazelbuild/stardoc/releases/download/0.5.0/stardoc-0.5.0.tar.gz",
+            "https://github.com/bazelbuild/stardoc/releases/download/0.5.0/stardoc-0.5.0.tar.gz",
+        ],
+    )

bazeldoc/internal/BUILD.bazel

@@ -0,0 +1,73 @@
+load("@bazel_skylib//:bzl_library.bzl", "bzl_library")
+
+package(default_visibility = ["//bazeldoc:__subpackages__"])
+
+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/internal/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/internal/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):
+    """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)

bazeldoc/internal/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/internal/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,
+)