From 14e5792436be613179c7e5a8edca250d6a5332d2 Mon Sep 17 00:00:00 2001 From: Tony Aiuto Date: Thu, 3 Feb 2022 21:22:57 -0500 Subject: [PATCH 1/4] Try to make the docs a little better. - Fix stardoc adding

in markdown tables. - Add rough capability to handle macros that wrap a rule. The wrapping technique is: - In the wrapping macro, use the docstring @wraps(some_rule) - Then we don't emit the docs for the wrapper - In the docs for some_rule, replace the string "some_rule" with the name of the wrapper macro. It is a first attempt to make things better. It is crude, but it mostly works. --- doc_build/BUILD | 37 ++++++- doc_build/merge.py | 72 +++++++++++++ docs/latest.md | 226 +++++++++++++++++----------------------- pkg/pkg.bzl | 2 +- pkg/private/deb/deb.bzl | 2 +- 5 files changed, 202 insertions(+), 137 deletions(-) create mode 100755 doc_build/merge.py diff --git a/doc_build/BUILD b/doc_build/BUILD index 062e212a..d26aebe3 100644 --- a/doc_build/BUILD +++ b/doc_build/BUILD @@ -43,9 +43,8 @@ genrule( name = "reference", srcs = ["%s.md" % rule for rule, _ in ORDER], outs = ["reference.md"], - # Compensate for https://github.com/bazelbuild/stardoc/issues/118. - # Convert escaped HTML

  • back to raw text - cmd = "cat $(SRCS) | sed -e 's/<li>/
  • /g' >$@", + cmd = "$(location :merge) $(SRCS) >$@", + tools = [":merge"], ) [ @@ -108,3 +107,35 @@ bzl_library( ], visibility = ["//visibility:private"], ) +load("@rules_python//python:defs.bzl", "py_library") + +licenses(["notice"]) + +filegroup( + name = "standard_package", + srcs = [ + "BUILD", + ] + glob([ + "*.bzl", + "*.py", + ]), + visibility = ["//distro:__pkg__"], +) + +exports_files( + glob([ + "*.bzl", + ]), + visibility = [ + "//distro:__pkg__", + "//doc_build:__pkg__", + ], +) + +py_binary( + name = "merge", + srcs = ["merge.py"], + python_version = "PY3", + srcs_version = "PY3", + visibility = ["//visibility:private"], +) diff --git a/doc_build/merge.py b/doc_build/merge.py new file mode 100755 index 00000000..bb159941 --- /dev/null +++ b/doc_build/merge.py @@ -0,0 +1,72 @@ +#!/usr/bin/env python3 +# Copyright 2022 The Bazel Authors. All rights reserved. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +"""merge stardoc output into a single page. + +- concatenates files +- corrects things that stardoc botches +""" + +import re +import sys +import typing + + +ID_RE = re.compile(r'') +WRAPS_RE = re.compile(r'@wraps\((.*)\)') +CENTER_RE = re.compile(r'

    ([^<]*)

    ') + + +def merge_file(file: str, out, wrapper_map:typing.Dict[str, str]) -> None: + with open(file, 'r') as inp: + content = inp.read() + m = ID_RE.search(content) + this_pkg = m.group(1) if m else None + m = WRAPS_RE.search(content) + if m: + # I wrap something, so don't emit me. + wrapper_map[m.group(1)] = this_pkg + return + # If something wraps me, rewrite myself with the wrapper name. + if this_pkg in wrapper_map: + content = content.replace(this_pkg, wrapper_map[this_pkg]) + merge_text(content, out) + + +def merge_text(text: str, out) -> None: + for line in text.split('\n'): + if line.startswith('| :'): + line = fix_stardoc_table_align(line) + # Compensate for https://github.com/bazelbuild/stardoc/issues/118. + # Convert escaped HTML
  • back to raw text + line = line.replace('<li>', '
  • ') + line = CENTER_RE.sub(r'\1', line) + _ = out.write(line) + _ = out.write('\n') + +def fix_stardoc_table_align(line: str) -> str: + """Change centered descriptions to left justified.""" + if line.startswith('| :-------------: | :-------------: '): + return '| :------------ | :--------------- | :---------: | :---------: | :----------- |' + return line + + +def main(argv: typing.Sequence[str]) -> None: + wrapper_map = {} + for file in argv[1:]: + merge_file(file, sys.stdout, wrapper_map) + + +if __name__ == '__main__': + main(sys.argv) diff --git a/docs/latest.md b/docs/latest.md index a3076966..503d1002 100755 --- a/docs/latest.md +++ b/docs/latest.md @@ -26,6 +26,7 @@
  • strip_prefix
    • + ### Common Attributes @@ -75,6 +76,7 @@ should not be relied upon. Any other attributes should be specified as additional arguments to `pkg_attributes`. + Rule for creating Debian packages. @@ -84,36 +86,12 @@ Rule for creating Debian packages. ## pkg_deb 
    -pkg_deb(name, archive_name, kwargs)
-
    - -Creates a deb file. See pkg_deb_impl. - -**PARAMETERS** - - -| Name | Description | Default Value | -| :------------- | :------------- | :------------- | -| name |

    -

    | none | -| archive_name |

    -

    | None | -| kwargs |

    -

    | none | - - - - -Rule for creating Debian packages. - - - -## pkg_deb_impl - -
    -pkg_deb_impl(name, architecture, architecture_file, breaks, built_using, built_using_file,
-             conffiles, conffiles_file, config, conflicts, data, depends, depends_file, description,
-             description_file, distribution, enhances, homepage, maintainer, out, package,
-             package_file_name, package_variables, postinst, postrm, predepends, preinst, prerm,
-             priority, provides, recommends, replaces, section, suggests, templates, triggers,
-             urgency, version, version_file)
+pkg_deb(name, architecture, architecture_file, breaks, built_using, built_using_file,
+             conffiles, conffiles_file, config, conflicts, data, depends, depends_file, description,
+             description_file, distribution, enhances, homepage, maintainer, out, package,
+             package_file_name, package_variables, postinst, postrm, predepends, preinst, prerm,
+             priority, provides, recommends, replaces, section, suggests, templates, triggers,
+             urgency, version, version_file)
    @@ -123,45 +101,46 @@ pkg_deb_impl(name, name | A unique name for this target. | Name | required | | -| architecture | Package architecture. Must not be used with architecture_file. | String | optional | "all" | -| architecture_file | File that contains the package architecture. Must not be used with architecture. | Label | optional | None | -| breaks | See http://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps. | List of strings | optional | [] | -| built_using | The tool that were used to build this package provided either inline (with built_using) or from a file (with built_using_file). | String | optional | "" | -| built_using_file | The tool that were used to build this package provided either inline (with built_using) or from a file (with built_using_file). | Label | optional | None | -| conffiles | The list of conffiles or a file containing one conffile per line. Each item is an absolute path on the target system where the deb is installed. See https://www.debian.org/doc/debian-policy/ch-files.html#s-config-files. | List of strings | optional | [] | -| conffiles_file | The list of conffiles or a file containing one conffile per line. Each item is an absolute path on the target system where the deb is installed. See https://www.debian.org/doc/debian-policy/ch-files.html#s-config-files. | Label | optional | None | -| config | config file used for debconf integration. See https://www.debian.org/doc/debian-policy/ch-binary.html#prompting-in-maintainer-scripts. | Label | optional | None | -| conflicts | See http://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps. | List of strings | optional | [] | -| data | A tar file that contains the data for the debian package. | Label | required | | -| depends | See http://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps. | List of strings | optional | [] | -| depends_file | File that contains a list of package dependencies. Must not be used with depends. See http://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps. | Label | optional | None | -| description | The package description. Must not be used with description_file. | String | optional | "" | -| description_file | The package description. Must not be used with description. | Label | optional | None | -| distribution | "distribution: See http://www.debian.org/doc/debian-policy. | String | optional | "unstable" | -| enhances | See http://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps. | List of strings | optional | [] | -| homepage | The homepage of the project. | String | optional | "" | -| maintainer | The maintainer of the package. | String | required | | -| out | See Common Attributes | Label | required | | -| package | The name of the package | String | required | | -| package_file_name | See Common Attributes. Default: "{package}-{version}-{architecture}.deb | String | optional | "" | -| package_variables | See Common Attributes | Label | optional | None | -| postinst | The post-install script for the package. See http://www.debian.org/doc/debian-policy/ch-maintainerscripts.html. | Label | optional | None | -| postrm | The post-remove script for the package. See http://www.debian.org/doc/debian-policy/ch-maintainerscripts.html. | Label | optional | None | -| predepends | See http://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps. | List of strings | optional | [] | -| preinst | "The pre-install script for the package. See http://www.debian.org/doc/debian-policy/ch-maintainerscripts.html. | Label | optional | None | -| prerm | The pre-remove script for the package. See http://www.debian.org/doc/debian-policy/ch-maintainerscripts.html. | Label | optional | None | -| priority | The priority of the package. See http://www.debian.org/doc/debian-policy/ch-archive.html#s-priorities. | String | optional | "" | -| provides | See http://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps. | List of strings | optional | [] | -| recommends | See http://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps. | List of strings | optional | [] | -| replaces | See http://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps. | List of strings | optional | [] | -| section | The section of the package. See http://www.debian.org/doc/debian-policy/ch-archive.html#s-subsections. | String | optional | "" | -| suggests | See http://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps. | List of strings | optional | [] | -| templates | templates file used for debconf integration. See https://www.debian.org/doc/debian-policy/ch-binary.html#prompting-in-maintainer-scripts. | Label | optional | None | -| triggers | triggers file for configuring installation events exchanged by packages. See https://wiki.debian.org/DpkgTriggers. | Label | optional | None | -| urgency | "urgency: See http://www.debian.org/doc/debian-policy. | String | optional | "medium" | -| version | Package version. Must not be used with version_file. | String | optional | "" | -| version_file | File that contains the package version. Must not be used with version. | Label | optional | None | +| name | A unique name for this target. | Name | required | | +| architecture | Package architecture. Must not be used with architecture_file. | String | optional | "all" | +| architecture_file | File that contains the package architecture. Must not be used with architecture. | Label | optional | None | +| breaks | See http://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps. | List of strings | optional | [] | +| built_using | The tool that were used to build this package provided either inline (with built_using) or from a file (with built_using_file). | String | optional | "" | +| built_using_file | The tool that were used to build this package provided either inline (with built_using) or from a file (with built_using_file). | Label | optional | None | +| conffiles | The list of conffiles or a file containing one conffile per line. Each item is an absolute path on the target system where the deb is installed. See https://www.debian.org/doc/debian-policy/ch-files.html#s-config-files. | List of strings | optional | [] | +| conffiles_file | The list of conffiles or a file containing one conffile per line. Each item is an absolute path on the target system where the deb is installed. See https://www.debian.org/doc/debian-policy/ch-files.html#s-config-files. | Label | optional | None | +| config | config file used for debconf integration. See https://www.debian.org/doc/debian-policy/ch-binary.html#prompting-in-maintainer-scripts. | Label | optional | None | +| conflicts | See http://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps. | List of strings | optional | [] | +| data | A tar file that contains the data for the debian package. | Label | required | | +| depends | See http://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps. | List of strings | optional | [] | +| depends_file | File that contains a list of package dependencies. Must not be used with depends. See http://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps. | Label | optional | None | +| description | The package description. Must not be used with description_file. | String | optional | "" | +| description_file | The package description. Must not be used with description. | Label | optional | None | +| distribution | "distribution: See http://www.debian.org/doc/debian-policy. | String | optional | "unstable" | +| enhances | See http://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps. | List of strings | optional | [] | +| homepage | The homepage of the project. | String | optional | "" | +| maintainer | The maintainer of the package. | String | required | | +| out | See Common Attributes | Label | required | | +| package | The name of the package | String | required | | +| package_file_name | See Common Attributes. Default: "{package}-{version}-{architecture}.deb | String | optional | "" | +| package_variables | See Common Attributes | Label | optional | None | +| postinst | The post-install script for the package. See http://www.debian.org/doc/debian-policy/ch-maintainerscripts.html. | Label | optional | None | +| postrm | The post-remove script for the package. See http://www.debian.org/doc/debian-policy/ch-maintainerscripts.html. | Label | optional | None | +| predepends | See http://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps. | List of strings | optional | [] | +| preinst | "The pre-install script for the package. See http://www.debian.org/doc/debian-policy/ch-maintainerscripts.html. | Label | optional | None | +| prerm | The pre-remove script for the package. See http://www.debian.org/doc/debian-policy/ch-maintainerscripts.html. | Label | optional | None | +| priority | The priority of the package. See http://www.debian.org/doc/debian-policy/ch-archive.html#s-priorities. | String | optional | "" | +| provides | See http://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps. | List of strings | optional | [] | +| recommends | See http://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps. | List of strings | optional | [] | +| replaces | See http://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps. | List of strings | optional | [] | +| section | The section of the package. See http://www.debian.org/doc/debian-policy/ch-archive.html#s-subsections. | String | optional | "" | +| suggests | See http://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps. | List of strings | optional | [] | +| templates | templates file used for debconf integration. See https://www.debian.org/doc/debian-policy/ch-binary.html#prompting-in-maintainer-scripts. | Label | optional | None | +| triggers | triggers file for configuring installation events exchanged by packages. See https://wiki.debian.org/DpkgTriggers. | Label | optional | None | +| urgency | "urgency: See http://www.debian.org/doc/debian-policy. | String | optional | "medium" | +| version | Package version. Must not be used with version_file. | String | optional | "" | +| version_file | File that contains the package version. Must not be used with version. | Label | optional | None | + @@ -264,6 +243,7 @@ Creates an RPM format package via `pkg_filegroup` and friends. | version_file | File containing RPM "Version" tag. | Label | optional | None | + Rules for manipulation of various packaging. @@ -273,33 +253,10 @@ Rules for manipulation of various packaging. ## pkg_tar 
    -pkg_tar(name, kwargs)
-
    - -Creates a .tar file. See pkg_tar_impl. - -**PARAMETERS** - - -| Name | Description | Default Value | -| :------------- | :------------- | :------------- | -| name |

    -

    | none | -| kwargs |

    -

    | none | - - - - -Rules for manipulation of various packaging. - - - -## pkg_tar_impl - -
    -pkg_tar_impl(name, build_tar, compressor, compressor_args, deps, empty_dirs, empty_files, extension,
-             files, include_runfiles, mode, modes, mtime, out, owner, ownername, ownernames, owners,
-             package_base, package_dir, package_dir_file, package_file_name, package_variables,
-             portable_mtime, private_stamp_detect, remap_paths, srcs, stamp, strip_prefix, symlinks)
+pkg_tar(name, build_tar, compressor, compressor_args, deps, empty_dirs, empty_files, extension,
+             files, include_runfiles, mode, modes, mtime, out, owner, ownername, ownernames, owners,
+             package_base, package_dir, package_dir_file, package_file_name, package_variables,
+             portable_mtime, private_stamp_detect, remap_paths, srcs, stamp, strip_prefix, symlinks)
    @@ -309,36 +266,37 @@ pkg_tar_impl(name, name | A unique name for this target. | Name | required | | -| build_tar | - | Label | optional | //pkg/private:build_tar | -| compressor | - | Label | optional | None | -| compressor_args | - | String | optional | "" | -| deps | - | List of labels | optional | [] | -| empty_dirs | - | List of strings | optional | [] | -| empty_files | - | List of strings | optional | [] | -| extension | - | String | optional | "tar" | -| files | - | Dictionary: Label -> String | optional | {} | -| include_runfiles | - | Boolean | optional | False | -| mode | - | String | optional | "0555" | -| modes | - | Dictionary: String -> String | optional | {} | -| mtime | - | Integer | optional | -1 | -| out | - | Label | required | | -| owner | - | String | optional | "0.0" | -| ownername | - | String | optional | "." | -| ownernames | - | Dictionary: String -> String | optional | {} | -| owners | - | Dictionary: String -> String | optional | {} | -| package_base | - | String | optional | "./" | -| package_dir | - | String | optional | "" | -| package_dir_file | - | Label | optional | None | -| package_file_name | See Common Attributes | String | optional | "" | -| package_variables | See Common Attributes | Label | optional | None | -| portable_mtime | - | Boolean | optional | True | -| private_stamp_detect | - | Boolean | optional | False | -| remap_paths | - | Dictionary: String -> String | optional | {} | -| srcs | - | List of labels | optional | [] | -| stamp | Enable file time stamping. Possible values:
  • stamp = 1: Use the time of the build as the modification time of each file in the archive.
  • stamp = 0: Use an "epoch" time for the modification time of each file. This gives good build result caching.
  • stamp = -1: Control the chosen modification time using the --[no]stamp flag. | Integer | optional | 0 | -| strip_prefix | - | String | optional | "" | -| symlinks | - | Dictionary: String -> String | optional | {} | +| name | A unique name for this target. | Name | required | | +| build_tar | - | Label | optional | //pkg/private/tar:build_tar | +| compressor | - | Label | optional | None | +| compressor_args | - | String | optional | "" | +| deps | - | List of labels | optional | [] | +| empty_dirs | - | List of strings | optional | [] | +| empty_files | - | List of strings | optional | [] | +| extension | - | String | optional | "tar" | +| files | - | Dictionary: Label -> String | optional | {} | +| include_runfiles | - | Boolean | optional | False | +| mode | - | String | optional | "0555" | +| modes | - | Dictionary: String -> String | optional | {} | +| mtime | - | Integer | optional | -1 | +| out | - | Label | required | | +| owner | - | String | optional | "0.0" | +| ownername | - | String | optional | "." | +| ownernames | - | Dictionary: String -> String | optional | {} | +| owners | - | Dictionary: String -> String | optional | {} | +| package_base | - | String | optional | "./" | +| package_dir | - | String | optional | "" | +| package_dir_file | - | Label | optional | None | +| package_file_name | See Common Attributes | String | optional | "" | +| package_variables | See Common Attributes | Label | optional | None | +| portable_mtime | - | Boolean | optional | True | +| private_stamp_detect | - | Boolean | optional | False | +| remap_paths | - | Dictionary: String -> String | optional | {} | +| srcs | - | List of labels | optional | [] | +| stamp | Enable file time stamping. Possible values:
  • stamp = 1: Use the time of the build as the modification time of each file in the archive.
  • stamp = 0: Use an "epoch" time for the modification time of each file. This gives good build result caching.
  • stamp = -1: Control the chosen modification time using the --[no]stamp flag. | Integer | optional | 0 | +| strip_prefix | - | String | optional | "" | +| symlinks | - | Dictionary: String -> String | optional | {} | + @@ -360,8 +318,9 @@ Creates a .zip file. See pkg_zip_impl. | Name | Description | Default Value | | :------------- | :------------- | :------------- | -| name |

    -

    | none | -| kwargs |

    -

    | none | +| name | - | none | +| kwargs | - | none | + @@ -397,6 +356,7 @@ pkg_zip_impl(name, timestamp | Time stamp to place on all files in the archive, expressed as seconds since the Unix Epoch, as per RFC 3339. The default is January 01, 1980, 00:00 UTC.

    Due to limitations in the format of zip files, values before Jan 1, 1980 will be rounded up and the precision in the zip file is limited to a granularity of 2 seconds. | Integer | optional | 315532800 | + Package creation helper mapping rules. @@ -648,8 +608,8 @@ Create a symlink. | link_name | the path in the package that should point to the target. | none | | target | target path that the link should point to. | none | | attributes | file attributes. | None | -| src |

    -

    | None | -| kwargs |

    -

    | none | +| src | - | None | +| kwargs | - | none | @@ -679,7 +639,7 @@ strip_prefix.from_pkg(path) | Name | Description | Default Value | | :------------- | :------------- | :------------- | -| path |

    -

    | "" | +| path | - | "" | @@ -697,7 +657,8 @@ strip_prefix.from_root(path) | Name | Description | Default Value | | :------------- | :------------- | :------------- | -| path |

    -

    | "" | +| path | - | "" | + @@ -747,3 +708,4 @@ Legacy version | version_file | - | Label | optional | None | + diff --git a/pkg/pkg.bzl b/pkg/pkg.bzl index c9dfe78e..60efc3d5 100644 --- a/pkg/pkg.bzl +++ b/pkg/pkg.bzl @@ -315,7 +315,7 @@ pkg_tar_impl = rule( ) def pkg_tar(name, **kwargs): - """Creates a .tar file. See pkg_tar_impl.""" + """@wraps(pkg_tar_impl)""" # Compatibility with older versions of pkg_tar that define files as # a flat list of labels. diff --git a/pkg/private/deb/deb.bzl b/pkg/private/deb/deb.bzl index fa852239..bbf3e009 100644 --- a/pkg/private/deb/deb.bzl +++ b/pkg/private/deb/deb.bzl @@ -353,7 +353,7 @@ See https://www.debian.org/doc/debian-policy/ch-files.html#s-config-files.""", ) def pkg_deb(name, archive_name = None, **kwargs): - """Creates a deb file. See pkg_deb_impl.""" + """@wraps(pkg_deb_impl).""" if archive_name: # buildifier: disable=print print("'archive_name' is deprecated. Use 'package_file_name' or 'out' to name the output.") From 7ce0e40e5b4721e6edd958c496941ac49c38c97b Mon Sep 17 00:00:00 2001 From: Tony Aiuto Date: Fri, 4 Feb 2022 23:12:33 -0500 Subject: [PATCH 2/4] reorder BUILD to be more like th others --- doc_build/BUILD | 55 ++++++++++++++++++++++++------------------------- 1 file changed, 27 insertions(+), 28 deletions(-) diff --git a/doc_build/BUILD b/doc_build/BUILD index 92e33b12..c5368d47 100644 --- a/doc_build/BUILD +++ b/doc_build/BUILD @@ -11,16 +11,39 @@ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. +"""Generate the reference documentation. + +How to: + bazel build //doc_build:reference + cp bazel-bin/doc_build/reference.md docs/latest.md + git commit -m 'update docs' docs/latest.md +""" load("@bazel_skylib//:bzl_library.bzl", "bzl_library") load("@bazel_stardoc//stardoc:stardoc.bzl", "stardoc") +load("@rules_python//python:defs.bzl", "py_library") load("//:version.bzl", "version") -# HOW TO: -# bazel build //doc_build:reference -# cp bazel-bin/doc_build/reference.md docs/latest.md -# git commit -m 'update docs' docs/latest.md +filegroup( + name = "standard_package", + srcs = [ + "BUILD", + ] + glob([ + "*.bzl", + "*.py", + ]), + visibility = ["//distro:__pkg__"], +) +exports_files( + glob([ + "*.bzl", + ]), + visibility = [ + "//distro:__pkg__", + "//doc_build:__pkg__", + ], +) # pairs of rule name and the source file to get it from # buildifier: leave-alone, do not sort @@ -106,30 +129,6 @@ bzl_library( ], visibility = ["//visibility:private"], ) -load("@rules_python//python:defs.bzl", "py_library") - -licenses(["notice"]) - -filegroup( - name = "standard_package", - srcs = [ - "BUILD", - ] + glob([ - "*.bzl", - "*.py", - ]), - visibility = ["//distro:__pkg__"], -) - -exports_files( - glob([ - "*.bzl", - ]), - visibility = [ - "//distro:__pkg__", - "//doc_build:__pkg__", - ], -) py_binary( name = "merge", From 62392b57c313b8cce1694d569dce504aea419314 Mon Sep 17 00:00:00 2001 From: Tony Aiuto Date: Tue, 15 Feb 2022 20:35:28 -0500 Subject: [PATCH 3/4] function doc --- doc_build/merge.py | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/doc_build/merge.py b/doc_build/merge.py index bb159941..d4a7e550 100755 --- a/doc_build/merge.py +++ b/doc_build/merge.py @@ -45,6 +45,12 @@ def merge_file(file: str, out, wrapper_map:typing.Dict[str, str]) -> None: def merge_text(text: str, out) -> None: + """Merge a block of text into an output stream. + + Args: + text: block of text produced by Starroc. + out: an output file stream. + """ for line in text.split('\n'): if line.startswith('| :'): line = fix_stardoc_table_align(line) @@ -55,6 +61,7 @@ def merge_text(text: str, out) -> None: _ = out.write(line) _ = out.write('\n') + def fix_stardoc_table_align(line: str) -> str: """Change centered descriptions to left justified.""" if line.startswith('| :-------------: | :-------------: '): From bec0f625a246646c1eb2a81fa4b4343ef9142008 Mon Sep 17 00:00:00 2001 From: Tony Aiuto Date: Tue, 15 Feb 2022 23:44:09 -0500 Subject: [PATCH 4/4] exectools --- doc_build/BUILD | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc_build/BUILD b/doc_build/BUILD index 587c37e7..e4e3678c 100644 --- a/doc_build/BUILD +++ b/doc_build/BUILD @@ -66,7 +66,7 @@ genrule( srcs = ["%s.md" % rule for rule, _ in ORDER], outs = ["reference.md"], cmd = "$(location :merge) $(SRCS) >$@", - tools = [":merge"], + exec_tools = [":merge"], ) [