docs/build: Assorted fixes for building as external target (#29845)

Signed-off-by: Ryan Northey <ryan@synca.io>

Signed-off-by: phlax <phlax@users.noreply.github.com>

bazel/repositories.bzl

@@ -114,7 +114,7 @@ genrule(
     name = "project",
     outs = ["project.json"],
     cmd = """
-    $(location :get_project_json) . > $@
+    $(location :get_project_json) $$(dirname $(location @envoy//:VERSION.txt)) > $@
     """,
     tools = [
         ":get_project_json",

docs/BUILD

@@ -113,7 +113,7 @@ genrule(
     srcs = [":empty_extensions.json"],
     outs = ["empty_protos_rst.tar.gz"],
     cmd = """
-    $(location //tools/protodoc:generate_empty) \\
+    $(location //tools/protodoc:generate_empty) \
         $(location empty_extensions.json) $@
     """,
     exec_tools = ["//tools/protodoc:generate_empty"],
@@ -170,7 +170,7 @@ genrule(
     name = "version_histories",
     outs = ["version_histories.tar.gz"],
     cmd = """
-    $(location //tools/docs:generate_version_histories) $@
+    $(location //tools/docs:generate_version_histories) --path=$$(dirname $(location //:VERSION.txt)) $@
     """,
     exec_tools = [
         ":versions.yaml",
@@ -237,7 +237,7 @@ genrule(
          --build_sha="$${BUILD_DOCS_SHA:-$${BUILD_SCM_REVISION}}" \
          --docs_tag="$${BUILD_DOCS_TAG:-}" \
          --version_file=$(location //:VERSION.txt) \
-         --descriptor_path=$(location @envoy_api//:v3_proto_set) \\
+         --descriptor_path=$(location @envoy_api//:v3_proto_set) \
          $(location rst) \
          $@
     """,
@@ -258,6 +258,7 @@ genrule(
     cmd = """
     $(location //tools/docs:sphinx_runner) \
          $${SPHINX_RUNNER_ARGS:-} \
+         --build_sha="$${BUILD_DOCS_SHA:-}" \
          --version_file=$(location //:VERSION.txt) \
          --descriptor_path=$(location @envoy_api//:v3_proto_set) \
          $(location :rst) \
@@ -270,3 +271,8 @@ genrule(
         "@envoy_api//:v3_proto_set",
     ],
 )
+
+alias(
+    name = "docs",
+    actual = ":html",
+)

docs/build.sh

@@ -45,7 +45,7 @@ fi
 # Building html/rst is determined by then needs of CI but can be overridden in dev.
 if [[ "${BUILD_TYPE}" == "html" ]] || [[ -n "${DOCS_BUILD_HTML}" ]]; then
     BUILD_HTML=1
-    BUILD_HTML_TARGET="//docs:html"
+    BUILD_HTML_TARGET="//docs"
     BUILD_HTML_TARBALL="bazel-bin/docs/html.tar.gz"
     if [[ -n "${CI_BRANCH}" ]] || [[ -n "${DOCS_BUILD_RELEASE}" ]]; then
         # CI build - use git sha

tools/base/requirements.in

@@ -1,5 +1,6 @@
 abstracts>=0.0.12
 aio.api.bazel
+aio.api.github>=0.2.5
 aiohttp>=3.8.1
 cffi>=1.15.0
 clang-format==14.0.6
@@ -8,7 +9,7 @@ colorama
 coloredlogs
 cryptography>=41.0.1
 dependatool>=0.2.2
-envoy.base.utils>=0.4.11
+envoy.base.utils>=0.4.12
 envoy.code.check>=0.5.8
 envoy.dependency.check>=0.1.7
 envoy.distribution.release>=0.0.9

tools/base/requirements.txt

@@ -25,10 +25,11 @@ aio-api-bazel==0.0.2 \
     --hash=sha256:56e36463d236e477b7e282f2d870185a0b978b50e2c3803c1ebf8b8ac4b18f5b \
     --hash=sha256:d3f563b7698e874437d80538a89dd4d79bc37de2e850c846330ae456e3f21dcc
     # via -r requirements.in
-aio-api-github==0.2.4 \
-    --hash=sha256:ccbc7c6c61b25994e87474d78c48549e9fbc98c2cc04314b50b80ba1f40fd521 \
-    --hash=sha256:eccfccd1503f50384de3f6526bd780ca02107cb440a666b2c1ab978d99c7db5e
+aio-api-github==0.2.5 \
+    --hash=sha256:301a357209831ac2bc0fb5c79f8b8795a5363da5cabc2229f10155bdb6d42f5d \
+    --hash=sha256:3532d0892e875e8bb6b188c0beba4e8bac9d5147e249ce987bb2beef1e7b711e
     # via
+    #   -r requirements.in
     #   envoy-base-utils
     #   envoy-dependency-check
 aio-api-nist==0.0.3 \
@@ -442,9 +443,9 @@ docutils==0.19 \
     # via
     #   envoy-docs-sphinx-runner
     #   sphinx
-envoy-base-utils==0.4.11 \
-    --hash=sha256:5ced696c470b4c3090e6fc3f74e7e33f5fe217e775b1fc1fb56dfc756b781fbe \
-    --hash=sha256:97c79177bb89360b7772e58fb20c671c67bf0b6cdee74c0b9f8a80433f0370cc
+envoy-base-utils==0.4.12 \
+    --hash=sha256:2bafcb6be3c1223968c9ee90b7a33d6d93aee16fe99bef37410ea9e4bc1a957f \
+    --hash=sha256:b9b409abe83be6911aa03cfe635ed1e2e2b9e44e7c8595b2b7e5c7aae7bf70fc
     # via
     #   -r requirements.in
     #   envoy-code-check

tools/docs/BUILD

@@ -42,6 +42,7 @@ py_binary(
 envoy_entry_point(
     name = "sphinx_runner",
     pkg = "envoy.docs.sphinx_runner",
+    visibility = ["//visibility:public"],
 )
 
 py_binary(

tools/docs/generate_version_histories.py

@@ -6,7 +6,7 @@
 
 from frozendict import frozendict
 import jinja2
-from packaging import version
+from packaging import version as _version
 
 from aio.run import runner
 
@@ -147,7 +147,7 @@ def jinja_env(self) -> jinja2.Environment:
 
     @cached_property
     def project(self) -> IProject:
-        return Project()
+        return Project(path=self.args.path)
 
     @cached_property
     def sections(self) -> frozendict:
@@ -171,6 +171,7 @@ def version_history_tpl(self):
 
     def add_arguments(self, parser) -> None:
         super().add_arguments(parser)
+        parser.add_argument("--path")
         parser.add_argument("output_file")
 
     def minor_index_path(self, minor_version) -> pathlib.Path:
@@ -192,7 +193,7 @@ async def write_version_histories(self) -> None:
         for changelog_version in self.project.changelogs:
             await self.write_version_history(changelog_version)
 
-    async def write_version_history(self, changelog_version: version.Version) -> None:
+    async def write_version_history(self, changelog_version: _version.Version) -> None:
         minor_version = utils.minor_version_for(changelog_version)
         root_path = self.tpath.joinpath(f"v{minor_version.base_version}")
         root_path.mkdir(parents=True, exist_ok=True)
@@ -258,7 +259,7 @@ async def write_version_history_minor_indeces(self) -> None:
             await self.write_version_history_minor_index(minor_version, patches)
 
     async def write_version_history_minor_index(
-            self, minor_version: version.Version, patch_versions) -> None:
+            self, minor_version: _version.Version, patch_versions) -> None:
         skip_first = (self.project.is_dev and self.project.is_current(patch_versions[0]))
         if skip_first:
             patch_versions = patch_versions[1:]

tools/protodoc/protodoc.bzl

@@ -12,7 +12,7 @@ def _protodoc_impl(target, ctx):
 #
 # The aspect builds the transitive docs, so any .proto in the dependency graph
 # get docs created.
-protodoc_aspect = api_proto_plugin_aspect("//tools/protodoc", _protodoc_impl)
+protodoc_aspect = api_proto_plugin_aspect("@envoy//tools/protodoc", _protodoc_impl)
 
 def _protodoc_rule_impl(ctx):
     deps = []