extensions: Use bazel build for generating docs rst

.github/dependabot.yml

@@ -21,6 +21,11 @@ updates:
     schedule:
       interval: "daily"
 
+  - package-ecosystem: "pip"
+    directory: "/tools/docs"
+    schedule:
+      interval: "daily"
+
   - package-ecosystem: "pip"
     directory: "/tools/github"
     schedule:

bazel/repositories_extra.bzl

@@ -36,6 +36,11 @@ def _python_deps():
         # release_date = "2019-02-23"
         # use_category = ["test"],
     )
+    pip_install(
+        name = "docs_pip3",
+        requirements = "@envoy//tools/docs:requirements.txt",
+        extra_pip_args = ["--require-hashes"],
+    )
     pip_install(
         name = "deps_pip3",
         requirements = "@envoy//tools/dependency:requirements.txt",

docs/build.sh

@@ -75,7 +75,7 @@ BAZEL_BUILD_OPTIONS+=(
 
 # Generate RST for the lists of trusted/untrusted extensions in
 # intro/arch_overview/security docs.
-bazel run "${BAZEL_BUILD_OPTIONS[@]}" //tools/extensions:generate_extension_rst
+bazel build "${BAZEL_BUILD_OPTIONS[@]}" //tools/docs:extensions_security_rst
 
 # Generate RST for external dependency docs in intro/arch_overview/security.
 bazel run "${BAZEL_BUILD_OPTIONS[@]}" //tools/dependency:generate_external_dep_rst
@@ -145,6 +145,9 @@ rsync -av \
       "${SCRIPT_DIR}"/_ext \
       "${GENERATED_RST_DIR}"
 
+# TODO(phlax): once all of above jobs are moved to bazel build genrules this can be done as part of the sphinx build
+tar -xf bazel-out/k8-fastbuild/bin/tools/docs/extensions_security_rst.tar -C "${GENERATED_RST_DIR}"
+
 # Merge generated redirects
 jq -r 'with_entries(.key |= sub("^envoy/";"api-v3/")) | with_entries(.value |= sub("^envoy/";"api-v2/")) | to_entries[] | "\(.value)\t\t\(.key)"' docs/v2_mapping.json >> "${GENERATED_RST_DIR}"/redirects.txt
 

tools/docs/BUILD

@@ -0,0 +1,26 @@
+load("@rules_python//python:defs.bzl", "py_binary")
+load("//bazel:envoy_build_system.bzl", "envoy_package")
+load("@docs_pip3//:requirements.bzl", "requirement")
+
+licenses(["notice"])  # Apache 2
+
+envoy_package()
+
+py_binary(
+    name = "generate_extensions_security_rst",
+    srcs = ["generate_extensions_security_rst.py"],
+    data = ["//source/extensions:extensions_metadata.yaml"],
+    deps = [
+        requirement("pyyaml"),
+    ],
+)
+
+genrule(
+    name = "extensions_security_rst",
+    srcs = ["//source/extensions:extensions_metadata.yaml"],
+    outs = ["extensions_security_rst.tar"],
+    cmd = (
+        "$(location generate_extensions_security_rst) $(location //source/extensions:extensions_metadata.yaml) $@"
+    ),
+    tools = [":generate_extensions_security_rst"],
+)

tools/extensions/generate_extension_rst.py → tools/docs/generate_extensions_security_rst.py

@@ -5,6 +5,8 @@
 from collections import defaultdict
 import os
 import pathlib
+import sys
+import tarfile
 
 import yaml
 
@@ -19,15 +21,13 @@ def format_item(extension, metadata):
     return item
 
 
-if __name__ == '__main__':
-    try:
-        generated_rst_dir = os.environ["GENERATED_RST_DIR"]
-    except KeyError:
-        raise SystemExit(
-            "Path to an output directory must be specified with GENERATED_RST_DIR env var")
+def main():
+    metadata_filepath = sys.argv[1]
+    output_filename = sys.argv[2]
+    generated_rst_dir = os.path.dirname(output_filename)
     security_rst_root = os.path.join(generated_rst_dir, "intro/arch_overview/security")
 
-    with open("source/extensions/extensions_metadata.yaml") as f:
+    with open(metadata_filepath) as f:
         extension_db = yaml.safe_load(f.read())
 
     pathlib.Path(security_rst_root).mkdir(parents=True, exist_ok=True)
@@ -43,3 +43,10 @@ def format_item(extension, metadata):
             for extension in sorted(extensions)
             if extension_db[extension].get('status') != 'wip')
         output_path.write_text(content)
+
+    with tarfile.open(output_filename, "w") as tar:
+        tar.add(generated_rst_dir, arcname=".")
+
+
+if __name__ == '__main__':
+    sys.exit(main())

tools/docs/requirements.txt

@@ -0,0 +1,37 @@
+#
+# This file is autogenerated by pip-compile
+# To update, run:
+#
+#    pip-compile --generate-hashes tools/docs/requirements.txt
+#
+pyyaml==5.4.1 \
+    --hash=sha256:08682f6b72c722394747bddaf0aa62277e02557c0fd1c42cb853016a38f8dedf \
+    --hash=sha256:0f5f5786c0e09baddcd8b4b45f20a7b5d61a7e7e99846e3c799b05c7c53fa696 \
+    --hash=sha256:129def1b7c1bf22faffd67b8f3724645203b79d8f4cc81f674654d9902cb4393 \
+    --hash=sha256:294db365efa064d00b8d1ef65d8ea2c3426ac366c0c4368d930bf1c5fb497f77 \
+    --hash=sha256:3b2b1824fe7112845700f815ff6a489360226a5609b96ec2190a45e62a9fc922 \
+    --hash=sha256:3bd0e463264cf257d1ffd2e40223b197271046d09dadf73a0fe82b9c1fc385a5 \
+    --hash=sha256:4465124ef1b18d9ace298060f4eccc64b0850899ac4ac53294547536533800c8 \
+    --hash=sha256:49d4cdd9065b9b6e206d0595fee27a96b5dd22618e7520c33204a4a3239d5b10 \
+    --hash=sha256:4e0583d24c881e14342eaf4ec5fbc97f934b999a6828693a99157fde912540cc \
+    --hash=sha256:5accb17103e43963b80e6f837831f38d314a0495500067cb25afab2e8d7a4018 \
+    --hash=sha256:607774cbba28732bfa802b54baa7484215f530991055bb562efbed5b2f20a45e \
+    --hash=sha256:6c78645d400265a062508ae399b60b8c167bf003db364ecb26dcab2bda048253 \
+    --hash=sha256:72a01f726a9c7851ca9bfad6fd09ca4e090a023c00945ea05ba1638c09dc3347 \
+    --hash=sha256:74c1485f7707cf707a7aef42ef6322b8f97921bd89be2ab6317fd782c2d53183 \
+    --hash=sha256:895f61ef02e8fed38159bb70f7e100e00f471eae2bc838cd0f4ebb21e28f8541 \
+    --hash=sha256:8c1be557ee92a20f184922c7b6424e8ab6691788e6d86137c5d93c1a6ec1b8fb \
+    --hash=sha256:bb4191dfc9306777bc594117aee052446b3fa88737cd13b7188d0e7aa8162185 \
+    --hash=sha256:bfb51918d4ff3d77c1c856a9699f8492c612cde32fd3bcd344af9be34999bfdc \
+    --hash=sha256:c20cfa2d49991c8b4147af39859b167664f2ad4561704ee74c1de03318e898db \
+    --hash=sha256:cb333c16912324fd5f769fff6bc5de372e9e7a202247b48870bc251ed40239aa \
+    --hash=sha256:d2d9808ea7b4af864f35ea216be506ecec180628aced0704e34aca0b040ffe46 \
+    --hash=sha256:d483ad4e639292c90170eb6f7783ad19490e7a8defb3e46f97dfe4bacae89122 \
+    --hash=sha256:dd5de0646207f053eb0d6c74ae45ba98c3395a571a2891858e87df7c9b9bd51b \
+    --hash=sha256:e1d4970ea66be07ae37a3c2e48b5ec63f7ba6804bdddfdbd3cfd954d25a82e63 \
+    --hash=sha256:e4fac90784481d221a8e4b1162afa7c47ed953be40d31ab4629ae917510051df \
+    --hash=sha256:fa5ae20527d8e831e8230cbffd9f8fe952815b2b7dae6ffec25318803a7528fc \
+    --hash=sha256:fd7f6999a8070df521b6384004ef42833b9bd62cfee11a09bda1079b4b704247 \
+    --hash=sha256:fdc842473cd33f45ff6bce46aea678a54e3d21f1b61a7750ce3c498eedfe25d6 \
+    --hash=sha256:fe69978f3f768926cfa37b867e3843918e012cf83f680806599ddce33c2c68b0
+    # via -r tools/docs/requirements.txt

tools/extensions/BUILD

@@ -16,9 +16,3 @@ py_binary(
         "//test/extensions/filters/network/common/fuzz:uber_per_readfilter.cc",
     ] + envoy_all_extensions(),
 )
-
-py_binary(
-    name = "generate_extension_rst",
-    srcs = ["generate_extension_rst.py"],
-    data = ["//source/extensions:extensions_metadata.yaml"],
-)