diff --git a/.bazelrc b/.bazelrc new file mode 100644 index 0000000..c3744bf --- /dev/null +++ b/.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 diff --git a/.github/workflows/bazel.yml b/.github/workflows/bazel.yml new file mode 100644 index 0000000..b02d9f0 --- /dev/null +++ b/.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 <") + final_content.extend(content) + final_content.append("") + + write_file( + name = name, + out = out, + content = final_content, + ) diff --git a/bazeldoc/internal/write_file_list.bzl b/bazeldoc/internal/write_file_list.bzl new file mode 100644 index 0000000..666ff03 --- /dev/null +++ b/bazeldoc/internal/write_file_list.bzl @@ -0,0 +1,48 @@ +load(":write_doc.bzl", "write_doc") +load(":doc_utilities.bzl", "doc_utilities") + +def write_file_list( + name, + out, + header_content = [], + doc_provs = [], + doc_path = "doc", + do_not_edit_warning = True): + """Defines a target that writes a documentation file that contains a header and a list of files. + + Args: + name: The name of the target. + out: The basename of the output filename as a `string`. + header_content: A `list` of strings representing the header content of + the file. + doc_provs: A `list` of document provider `struct` values as returned + from `providers.create()`. + doc_path: The relative path for the documentation directory. Do not + include a leading or trailing slash. + do_not_edit_warning: A `bool` specifying whether a comment should be + added to the top of the written file. + + Returns: + None. + """ + content = [] + content.extend(header_content) + if doc_provs != []: + content.extend([ + doc_utilities.toc_entry(r.name, "/{doc_path}/{src_doc}".format( + doc_path = doc_path, + src_doc = r.doc_basename, + )) + for r in doc_provs + ]) + content.append("") + + if out == None: + out = name + ".vm" + + write_doc( + name = name, + out = out, + content = content, + do_not_edit_warning = do_not_edit_warning, + ) diff --git a/bazeldoc/internal/write_header.bzl b/bazeldoc/internal/write_header.bzl new file mode 100644 index 0000000..abeffea --- /dev/null +++ b/bazeldoc/internal/write_header.bzl @@ -0,0 +1,45 @@ +load(":write_doc.bzl", "write_doc") +load(":doc_utilities.bzl", "doc_utilities") + +def write_header( + name, + out = None, + header_content = [], + symbols = [], + do_not_edit_warning = True): + """Defines a target that writes a header file that will be used as a header template for a `stardoc` rule. + + Args: + name: The name of the target. + out: The basename of the output filename as a `string`. + header_content: A `list` of strings representing the header content of + the file. + symbols: A `list` of symbol names that will be included in the documentation. + do_not_edit_warning: A `bool` specifying whether a comment should be + added to the top of the written file. + + Returns: + None. + """ + content = [] + content.extend(header_content) + if symbols != []: + content.extend([ + "", + "On this page:", + "", + ]) + content.extend( + [doc_utilities.toc_entry(s, "#{0}".format(s)) for s in symbols], + ) + content.append("") + + if out == None: + out = name + ".vm" + + write_doc( + name = name, + out = out, + content = content, + do_not_edit_warning = do_not_edit_warning, + ) diff --git a/ci.bazelrc b/ci.bazelrc new file mode 100644 index 0000000..e5458ef --- /dev/null +++ b/ci.bazelrc @@ -0,0 +1,14 @@ +# CI Settings for Bazel + +# Output information about the flags that are applied +common:ci --announce_rc + +# Disable color +common:ci --color=no + +# Information about Github Action hosted runners +# https://docs.github.com/en/free-pro-team@latest/actions/reference/specifications-for-github-hosted-runners#supported-runners-and-hardware-resources +build:ci --local_cpu_resources=2 + +# Test output information +test:ci --test_output=errors --test_summary=detailed diff --git a/doc/BUILD.bazel b/doc/BUILD.bazel new file mode 100644 index 0000000..4cc5ab3 --- /dev/null +++ b/doc/BUILD.bazel @@ -0,0 +1,91 @@ +load( + "//bazeldoc:bazeldoc.bzl", + "doc_for_provs", + "write_file_list", + "write_header", + doc_providers = "providers", +) + +# Lovingly inspired by +# https://github.com/bazelbuild/rules_swift/blob/021c11b1d578ffba547140eb24854cdfe74c794f/doc/BUILD.bazel#L3 + +# MARK: - Documentation Declarations + +_API_SRCS = [ + "providers", +] + +_API_DOC_PROVIDERS = [ + doc_providers.create( + name = name, + stardoc_input = "//bazeldoc:bazeldoc.bzl", + symbols = [name], + deps = ["//bazeldoc"], + ) + for name in _API_SRCS +] + +_BUILD_RULES_PROV = doc_providers.create( + name = "build_rules_overview", + stardoc_input = "//bazeldoc:bazeldoc.bzl", + symbols = [ + "doc_for_provs", + "write_header", + "write_file_list", + ], + deps = ["//bazeldoc"], +) + +_ALL_DOC_PROVIDERS = [ + _BUILD_RULES_PROV, + doc_providers.create( + name = "api", + is_stardoc = False, + stardoc_input = "//bazeldoc:bazeldoc.bzl", + deps = ["//bazeldoc"], + ), +] + _API_DOC_PROVIDERS + +# MARK: - Special Case api.md + +write_file_list( + name = "api_doc", + out = "api.md_", + doc_provs = _API_DOC_PROVIDERS, + header_content = [ + "# Documentation API", + "", + "The APIs described below are used by ", + "[the build rules](/doc/build_rules_overview.md) to facilitate the ", + "generation of the Starlark documentation.", + "", + ], +) + +# MARK: - Headers + +write_header( + name = "build_rules_overview_header", + header_content = [ + "# Build Rules", + "", + "The macros described below are used to generate, test and copy ", + "Starlark documentation.", + ], + symbols = _BUILD_RULES_PROV.symbols, +) + +# Write the API headers +[ + write_header( + name = doc_prov.header_label, + out = doc_prov.header_basename, + header_content = [ + "# `{name}` API".format(name = doc_prov.name), + ], + ) + for doc_prov in _API_DOC_PROVIDERS + if doc_prov.is_stardoc +] + +doc_for_provs(doc_provs = _ALL_DOC_PROVIDERS) diff --git a/doc/README.md b/doc/README.md new file mode 100644 index 0000000..f0e5ad0 --- /dev/null +++ b/doc/README.md @@ -0,0 +1,4 @@ +# Bazeldoc API + +- [API documentation](/doc/api.md) +- [Build rules and macros](/doc/build_rules_overview.md) diff --git a/doc/api.md b/doc/api.md new file mode 100755 index 0000000..d85dca2 --- /dev/null +++ b/doc/api.md @@ -0,0 +1,9 @@ + +# Documentation API + +The APIs described below are used by +[the build rules](/doc/build_rules_overview.md) to facilitate the +generation of the Starlark documentation. + + * [providers](/doc/providers.md) + diff --git a/doc/build_rules_overview.md b/doc/build_rules_overview.md new file mode 100755 index 0000000..08d49d4 --- /dev/null +++ b/doc/build_rules_overview.md @@ -0,0 +1,88 @@ + +# Build Rules + +The macros described below are used to generate, test and copy +Starlark documentation. + +On this page: + + * [doc_for_provs](#doc_for_provs) + * [write_header](#write_header) + * [write_file_list](#write_file_list) + + + + +## doc_for_provs + +
+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. + +**PARAMETERS** + + +| Name | Description | Default Value | +| :------------- | :------------- | :------------- | +| doc_provs | A list of document provider struct values as returned from providers.create(). | none | + +**RETURNS** + +None. + + + + +## write_file_list + +
+write_file_list(name, out, header_content, doc_provs, doc_path, do_not_edit_warning)
+
+ +Defines a target that writes a documentation file that contains a header and a list of files. + +**PARAMETERS** + + +| Name | Description | Default Value | +| :------------- | :------------- | :------------- | +| name | The name of the target. | none | +| out | The basename of the output filename as a string. | none | +| header_content | A list of strings representing the header content of the file. | [] | +| doc_provs | A list of document provider struct values as returned from providers.create(). | [] | +| doc_path | The relative path for the documentation directory. Do not include a leading or trailing slash. | "doc" | +| do_not_edit_warning | A bool specifying whether a comment should be added to the top of the written file. | True | + +**RETURNS** + +None. + + + + +## write_header + +
+write_header(name, out, header_content, symbols, do_not_edit_warning)
+
+ +Defines a target that writes a header file that will be used as a header template for a `stardoc` rule. + +**PARAMETERS** + + +| Name | Description | Default Value | +| :------------- | :------------- | :------------- | +| name | The name of the target. | none | +| out | The basename of the output filename as a string. | None | +| header_content | A list of strings representing the header content of the file. | [] | +| symbols | A list of symbol names that will be included in the documentation. | [] | +| do_not_edit_warning | A bool specifying whether a comment should be added to the top of the written file. | True | + +**RETURNS** + +None. + + diff --git a/doc/providers.md b/doc/providers.md new file mode 100755 index 0000000..7fc9009 --- /dev/null +++ b/doc/providers.md @@ -0,0 +1,36 @@ + +# `providers` API + + + + +## providers.create + +
+providers.create(name, stardoc_input, deps, doc_label, out_basename, doc_basename, header_label,
+                 header_basename, symbols, is_stardoc)
+
+ +Create a documentation provider. + +**PARAMETERS** + + +| Name | Description | Default Value | +| :------------- | :------------- | :------------- | +| 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. | none | +| stardoc_input | A string representing the input label provided to the stardoc declaration. | none | +| deps | A list of deps for the stardoc rule. | none | +| doc_label | Optional. A string which is the doc label name. | None | +| out_basename | Optional. A string which is the basename for the output file. | None | +| doc_basename | Optional. A string which is the basename for the final documentation file. | None | +| header_label | Optional. A string which is the header label name, if the header is being generated. | None | +| header_basename | Optional. The basename (string) of the header filename file, if one is being used. | None | +| symbols | Optional. A list of symbol names that should be included in the documentation. | None | +| is_stardoc | A bool indicating whether a stardoc declaration should be created. | True | + +**RETURNS** + +A `struct` representing a documentation provider. + + diff --git a/shared.bazelrc b/shared.bazelrc new file mode 100644 index 0000000..77f1598 --- /dev/null +++ b/shared.bazelrc @@ -0,0 +1,7 @@ +# Verbose Failures +build --verbose_failures + +# Strict PATH. Helps prevent build cache invalidation due to PATH differences. +build --incompatible_strict_action_env=true + +