Add a version indicator and selector to all docs pages

scripts/docs/BUILD

@@ -7,6 +7,7 @@ genrule(
     name = "gen_release_docs",
     srcs = [
         ":new_toc.yaml",
+        ":new_buttons.html",
         "//site/en:docs",
         "//src/main/java/com/google/devtools/build/lib:reference-docs.zip",
     ],
@@ -16,6 +17,7 @@ genrule(
     cmd = "$(location :create_release_docs)" +
           " --version=" + BUILD_SCM_REV_CMD +
           " --toc_path=$(location :new_toc.yaml)" +
+          " --buttons_path=$(location :new_buttons.html)" +
           " --narrative_docs_path=$(location //site/en:docs)" +
           " --reference_docs_path=$(location //src/main/java/com/google/devtools/build/lib:reference-docs.zip)" +
           " --output_path=$(OUTS)",
@@ -30,12 +32,18 @@ genrule(
     name = "gen_new_toc",
     srcs = [
         "//site/en:versions/_toc.yaml",
+        "//site/en:_buttons.html",
+    ],
+    outs = [
+        "new_toc.yaml",
+        "new_buttons.html",
     ],
-    outs = ["new_toc.yaml"],
     cmd = "$(location //src/main/java/com/google/devtools/build/docgen/release:toc_updater)" +
           " -i $(location //site/en:versions/_toc.yaml)" +
-          " -o $(OUTS)" +
-          " -v " + BUILD_SCM_REV_CMD,
+          " -o $(location new_toc.yaml)" +
+          " -v " + BUILD_SCM_REV_CMD +
+          " --version_indicator_input=$(location //site/en:_buttons.html)" +
+          " --version_indicator_output=$(location new_buttons.html)",
     stamp = 1,
     tools = [
         "//src/main/java/com/google/devtools/build/docgen/release:toc_updater",

scripts/docs/create_release_docs.py

@@ -34,6 +34,11 @@
     None,
     "Path to the _toc.yaml file that contains the table of contents for the versions menu.",
 )
+flags.DEFINE_string(
+  "buttons_path",
+  None,
+  "Path to the _buttons.html file that contains the version indicator.",
+)
 flags.DEFINE_string(
     "narrative_docs_path",
     None,
@@ -70,14 +75,16 @@ def validate_flag(name):
   exit(1)
 
 
-def create_docs_tree(version, toc_path, narrative_docs_path,
+def create_docs_tree(version, toc_path, buttons_path, narrative_docs_path,
                      reference_docs_path):
   """Creates a directory tree containing the docs for the Bazel version.
 
   Args:
     version: Version of this Bazel release.
     toc_path: Absolute path to the _toc.yaml file that lists the most recent
       Bazel versions.
+    buttons_path: Absolute path of the _buttons.html file that contains the
+      version indicator.
     narrative_docs_path: Absolute path of an archive that contains the narrative
       documentation (can be .zip or .tar).
     reference_docs_path: Absolute path of an archive that contains the reference
@@ -101,7 +108,11 @@ def create_docs_tree(version, toc_path, narrative_docs_path,
   try_extract(narrative_docs_path, release_dir)
   try_extract(reference_docs_path, release_dir)
 
-  return root_dir, toc_dest_path
+  buttons_dest_path = os.path.join(release_dir, "_buttons.html")
+  os.remove(buttons_dest_path)
+  shutil.copyfile(buttons_path, buttons_dest_path)
+
+  return root_dir, toc_dest_path, release_dir
 
 
 def try_extract(archive_path, output_dir):
@@ -128,7 +139,7 @@ def try_extract(archive_path, output_dir):
     archive.extractall(output_dir)
 
 
-def build_archive(version, root_dir, toc_path, output_path):
+def build_archive(version, root_dir, toc_path, output_path, release_dir):
   """Builds a documentation archive for the given Bazel release.
 
   This function reads all documentation files from the tree rooted in root_dir,
@@ -141,24 +152,27 @@ def build_archive(version, root_dir, toc_path, output_path):
       tree.
     toc_path: Absolute path of the _toc.yaml file.
     output_path: Absolute path where the archive should be written to.
+    release_dir: Absolute path of the root directory for this version.
   """
   with zipfile.ZipFile(output_path, "w") as archive:
     for root, _, files in os.walk(root_dir):
       for f in files:
         src = os.path.join(root, f)
         dest = src[len(root_dir) + 1:]
+        rel_path = os.path.relpath(src, release_dir)
 
         if src != toc_path and rewriter.can_rewrite(src):
-          archive.writestr(dest, get_versioned_content(src, version))
+          archive.writestr(dest, get_versioned_content(src, rel_path, version))
         else:
           archive.write(src, dest)
 
 
-def get_versioned_content(path, version):
+def get_versioned_content(path, rel_path, version):
   """Rewrites links in the given file to point at versioned docs.
 
   Args:
     path: Absolute path of the file that should be rewritten.
+    rel_path: Relative path of the file that should be rewritten.
     version: Version of the Bazel release whose documentation is being built.
 
   Returns:
@@ -167,15 +181,16 @@ def get_versioned_content(path, version):
   with open(path, "rt", encoding="utf-8") as f:
     content = f.read()
 
-  return rewriter.rewrite_links(path, content, version)
+  return rewriter.rewrite_links(path, content, rel_path, version)
 
 
 def main(unused_argv):
   version = validate_flag("version")
   output_path = validate_flag("output_path")
-  root_dir, toc_path = create_docs_tree(
+  root_dir, toc_path, release_dir = create_docs_tree(
       version=version,
       toc_path=validate_flag("toc_path"),
+    buttons_path=validate_flag("buttons_path"),
       narrative_docs_path=validate_flag("narrative_docs_path"),
       reference_docs_path=validate_flag("reference_docs_path"),
   )
@@ -185,6 +200,7 @@ def main(unused_argv):
       root_dir=root_dir,
       toc_path=toc_path,
       output_path=output_path,
+      release_dir=release_dir,
   )
 
 

scripts/docs/rewriter.py

@@ -26,28 +26,34 @@
     r"((href|src)\s*=\s*[\"']({})?)/".format(_BASE_URL))
 
 
-def _fix_html_links(content, version):
+def _fix_html_links(content, _rel_path, version):
   return _HTML_LINK_PATTERN.sub(r"\1/versions/{}/".format(version), content)
 
 
-def _fix_html_metadata(content, version):
+def _fix_html_metadata(content, _rel_path, version):
   return content.replace("value=\"/_book.yaml\"",
                          "value=\"/versions/{}/_book.yaml\"".format(version))
 
 
+def _set_header_vars(content, rel_path, version):
+  return content.replace("""{% include "_buttons.html" %}""", f"""{{% dynamic setvar version "{version}" %}}
+{{% dynamic setvar original_path "/{rel_path[:-len(os.path.splitext(rel_path)[1])]}" %}}
+{{% include "_buttons.html" %}}""")
+
+
 _MD_LINK_OR_IMAGE_PATTERN = re.compile(
     r"(\!?\[.*?\]\(({})?)(/.*?)\)".format(_BASE_URL))
 
 
-def _fix_md_links_and_images(content, version):
+def _fix_md_links_and_images(content, _rel_path, version):
   return _MD_LINK_OR_IMAGE_PATTERN.sub(r"\1/versions/{}\3)".format(version),
                                        content)
 
 
 _MD_METADATA_PATTERN = re.compile(r"^(Book: )(/.+)$", re.MULTILINE)
 
 
-def _fix_md_metadata(content, version):
+def _fix_md_metadata(content, _rel_path, version):
   return _MD_METADATA_PATTERN.sub(r"\1/versions/{}\2".format(version), content)
 
 
@@ -59,7 +65,7 @@ def _fix_md_metadata(content, version):
     ["/", "/_project.yaml", "/versions/", "/versions/_toc.yaml"])
 
 
-def _fix_yaml_paths(content, version):
+def _fix_yaml_paths(content, _rel_path, version):
 
   def sub(m):
     prefix, path, suffix = m.group(1, 4, 5)
@@ -72,7 +78,7 @@ def sub(m):
 
 
 _PURE_HTML_FIXES = [_fix_html_links, _fix_html_metadata]
-_PURE_MD_FIXES = [_fix_md_links_and_images, _fix_md_metadata]
+_PURE_MD_FIXES = [_fix_md_links_and_images, _fix_md_metadata, _set_header_vars]
 _PURE_YAML_FIXES = [_fix_yaml_paths]
 
 _FIXES = {
@@ -99,11 +105,12 @@ def can_rewrite(path):
   return bool(_get_fixes(path))
 
 
-def rewrite_links(path, content, version):
+def rewrite_links(path, content, rel_path, version):
   """Rewrites links in the given file to point to versioned docs.
 
   Args:
     path: Absolute path of the file to be rewritten.
+    rel_path: Relative path of the file to be rewritten.
     content: Content of said file, as text.
     version: Version of the Bazel release that is being built.
 
@@ -118,6 +125,6 @@ def rewrite_links(path, content, version):
 
   new_content = content
   for f in fixes:
-    new_content = f(new_content, version)
+    new_content = f(new_content, rel_path, version)
 
   return new_content

scripts/docs/rewriter_test.py

@@ -51,7 +51,7 @@ def testRewrite(self, basename):
     input_path, content = read_data_file(basename, "input")
     _, version = read_data_file("VERSION", "input")
 
-    actual = rewriter.rewrite_links(input_path, content, version)
+    actual = rewriter.rewrite_links(input_path, content, basename, version)
 
     _, expected = read_data_file(basename, "expected_output")
 

scripts/docs/testdata/expected_output/doc.md

@@ -3,6 +3,10 @@ Book: /versions/6.6.6/_book.yaml
 
 # Configurations
 
+{% dynamic setvar version "6.6.6" %}
+{% dynamic setvar original_path "/doc" %}
+{% include "_buttons.html" %}
+
 A build setting is a single piece of [configuration](/versions/6.6.6/rules/rules#configurations) information.
 
 Like all rules, build setting rules have [implementation functions](https://bazel.build/versions/6.6.6/rules/rules#implementation-function).

scripts/docs/testdata/expected_output/markdown_with_html.md

@@ -1,6 +1,10 @@
 Project: /_project.yaml
 Book: /versions/6.6.6/_book.yaml
 
+{% dynamic setvar version "6.6.6" %}
+{% dynamic setvar original_path "/markdown_with_html" %}
+{% include "_buttons.html" %}
+
 Lorem ipsum [short link](/versions/6.6.6/foo/bar). Or rather a [long link](https://bazel.build/versions/6.6.6/foo/bar)?
 
 ![Scalability graph](/versions/6.6.6/rules/scalability-graph.png "Scalability graph")

scripts/docs/testdata/input/doc.md

@@ -3,6 +3,8 @@ Book: /_book.yaml
 
 # Configurations
 
+{% include "_buttons.html" %}
+
 A build setting is a single piece of [configuration](/rules/rules#configurations) information.
 
 Like all rules, build setting rules have [implementation functions](https://bazel.build/rules/rules#implementation-function).

scripts/docs/testdata/input/markdown_with_html.md

@@ -1,6 +1,8 @@
 Project: /_project.yaml
 Book: /_book.yaml
 
+{% include "_buttons.html" %}
+
 Lorem ipsum [short link](/foo/bar). Or rather a [long link](https://bazel.build/foo/bar)?
 
 ![Scalability graph](/rules/scalability-graph.png "Scalability graph")

site/en/BUILD.bazel

@@ -7,6 +7,7 @@ exports_files(
     [
         "docs/user-manual.md",
         "versions/_toc.yaml",
+        "_buttons.html",
     ],
     visibility = [
         "//scripts/docs:__pkg__",

site/en/_buttons.html

@@ -10,4 +10,47 @@
   View source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span>
 </a>
 {% dynamic endif %}
+{% dynamic if not setvar.original_path %}
+{% dynamic setvar original_path %}{% dynamic print request.path %}{% dynamic endsetvar %}
+{% dynamic endif %}
+<span class="bazel-version-indicator">
+{% dynamic if not setvar.version %}
+<strong>Nightly</strong>
+{% dynamic else %}
+<a href="{% dynamic print setvar.original_path %}">Nightly</a>
+{% dynamic endif %}
+<!-- The lines below are updated by //scripts/docs:gen_new_toc -->
+<!-- BEGIN_VERSION_INDICATOR -->
+·
+{% dynamic if setvar.version == "7.2.0" %}
+<strong>7.2</strong>
+{% dynamic else %}
+<a href="/versions/7.2.0{% dynamic print setvar.original_path %}">7.2</a>
+{% dynamic endif %}
+·
+{% dynamic if setvar.version == "7.1.0" %}
+<strong>7.1</strong>
+{% dynamic else %}
+<a href="/versions/7.1.0{% dynamic print setvar.original_path %}">7.1</a>
+{% dynamic endif %}
+·
+{% dynamic if setvar.version == "7.0.0" %}
+<strong>7.0</strong>
+{% dynamic else %}
+<a href="/versions/7.0.0{% dynamic print setvar.original_path %}">7.0</a>
+{% dynamic endif %}
+·
+{% dynamic if setvar.version == "6.5.0" %}
+<strong>6.5</strong>
+{% dynamic else %}
+<a href="/versions/6.5.0{% dynamic print setvar.original_path %}">6.5</a>
+{% dynamic endif %}
+·
+{% dynamic if setvar.version == "6.4.0" %}
+<strong>6.4</strong>
+{% dynamic else %}
+<a href="/versions/6.4.0{% dynamic print setvar.original_path %}">6.4</a>
+{% dynamic endif %}
+<!-- END_VERSION_INDICATOR -->
+</span>
 </p>

site/en/bazel.css

@@ -136,3 +136,8 @@
   margin-inline-start: 8px;
   vertical-align: text-bottom;
 }
+
+.bazel-version-indicator {
+  float: right;
+  line-height: 36px;
+}

src/main/java/com/google/devtools/build/docgen/release/TableOfContentsOptions.java

@@ -38,6 +38,22 @@ public class TableOfContentsOptions extends OptionsBase {
       help = "Path of the YAML file where the new TOC should be written to.")
   public String outputPath;
 
+  @Option(
+      name = "version_indicator_input",
+      defaultValue = "",
+      documentationCategory = OptionDocumentationCategory.UNCATEGORIZED,
+      effectTags = {OptionEffectTag.UNKNOWN},
+      help = "Path of the file containing the version indicator.")
+  public String versionIndicatorInputPath;
+
+  @Option(
+      name = "version_indicator_output",
+      defaultValue = "",
+      documentationCategory = OptionDocumentationCategory.UNCATEGORIZED,
+      effectTags = {OptionEffectTag.UNKNOWN},
+      help = "Path of the file where the version indicator should be written.")
+  public String versionIndicatorOutputPath;
+
   @Option(
       name = "version",
       abbrev = 'v',