From fed085e319d47467b4cf12edc99704e9c781882e Mon Sep 17 00:00:00 2001
From: Andrew <73965466+wandrew0@users.noreply.github.com>
Date: Tue, 19 Mar 2024 15:01:33 -0700
Subject: [PATCH] tools: Fix test-documentation merge check errors.

Verified using the original test plan detailed in #18124, checking that the output
is similar, and error handling is correct if the virtualenv is not available.

Fixes #18124.
---
 tools/test-documentation | 172 +++++++++++++++++++++------------------
 1 file changed, 95 insertions(+), 77 deletions(-)

diff --git a/tools/test-documentation b/tools/test-documentation
index 5b7785406c..fb668a6605 100755
--- a/tools/test-documentation
+++ b/tools/test-documentation
@@ -1,92 +1,110 @@
-#!/usr/bin/env bash
-set -e
+#!/usr/bin/env python3
+import argparse
+import os
+import subprocess
+import sys
+from typing import Sequence
 
-color_message() {
-    local color_code="$1" message="$2"
-    printf '\e[%sm%s\e[0m\n' "$color_code" "$message" >&2
-}
+ZULIP_PATH = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+os.chdir(ZULIP_PATH)
+sys.path.insert(0, ZULIP_PATH)
 
-loglevel=()
+# check for the venv
+from tools.lib import sanity_check
 
-usage() {
-    cat <<EOF
-usage:
-  --help, -h                   show this help message and exit
-  --loglevel=LEVEL, -L LEVEL   log level (default: ERROR)
-  --skip-check-links           skip checking of links
-  --skip-external-links        skip checking of external links
-EOF
-}
+sanity_check.check_venv(__file__)
 
-args="$(getopt -o hL: --long help,loglevel:,skip-check-links,skip-external-links -- "$@")" \
-    || {
-        usage >&2
-        exit 1
-    }
-eval "set -- $args"
-while true; do
-    case "$1" in
-        -h | --help)
-            usage
-            exit 0
-            ;;
-        -L | --loglevel)
-            loglevel=("$1" "$2")
-            shift 2
-            ;;
-        --skip-check-links)
-            skip_check_links=1
-            shift
-            ;;
-        --skip-external-links)
-            skip_external_links=1
-            shift
-            ;;
-        --)
-            shift
-            break
-            ;;
-        *) exit 1 ;;
-    esac
-done
 
-cd "$(dirname "$0")"/../docs
+def color_message(color_code: str, message: str) -> None:
+    print(f"\033[0;{color_code}m{message}\033[0m", file=sys.stderr)
+
+
+parser = argparse.ArgumentParser()
+parser.add_argument(
+    "-L",
+    "--loglevel",
+    dest="loglevel",
+    nargs=1,
+    help="Log level (default: ERROR)",
+)
+parser.add_argument(
+    "--skip-check-links",
+    dest="skip_check_links",
+    action="store_true",
+    help="Skip checking of links.",
+)
+parser.add_argument(
+    "--skip-external-links",
+    dest="skip_external_link_check",
+    # default = false
+    action="store_true",
+    help="Skip checking of external links.",
+)
+options = parser.parse_args()
+# loglevel should be used as an extra command line option
+# in the form of ["-L", "LOGLEVEL"]
+# if loglevel is defined, insert "-L" ahead of loglevel
+if options.loglevel:
+    options.loglevel.insert(0, "-L")
+# if loglevel is undefined, make loglevel an empty list
+else:
+    options.loglevel = []
+
+os.chdir("docs")
 
 # collapse_navigation is set to False in conf.py to improve sidebar navigation for users.
 # However, we must change its value to True before we begin testing links.
 # Otherwise, sphinx would generate a large number of links we don't need to test.
-# The crawler would take a very long time to finish and TravisCI would fail as a result.
-make clean html O='-D html_theme_options.collapse_navigation=True'
+# The crawler would take a very long time to finish and GitHub Actions would fail as a result.
+subprocess.check_call(
+    ["make", "clean", "html", "O='-D html_theme_options.collapse_navigation=True'"]
+)
 
-err=0
+err = 0
 
-check() {
-    if "$@"; then
-        color_message 92 "Passed!"
-    else
-        color_message 91 "Failed!"
-        err=1
-    fi
-}
 
-color_message 94 "Validating HTML..."
-check java -jar ../node_modules/vnu-jar/build/dist/vnu.jar \
-    --filterfile ../tools/documentation.vnufilter \
-    --skip-non-html \
-    _build/html
+def check(args: Sequence[str]) -> None:
+    global err
+    if subprocess.call(args) == 0:
+        color_message("92", "Passed!")
+    else:
+        color_message("91", "Failed!")
+        err = 1
 
-if [ -n "$skip_check_links" ]; then
-    color_message 94 "Skipped testing links in documentation."
-else
-    cd ../tools/documentation_crawler
-    if [ -n "$skip_external_links" ]; then
-        color_message 94 "Testing only internal links in documentation..."
-        check scrapy crawl_with_status documentation_crawler -a skip_external=set "${loglevel[@]}"
+
+color_message("94", "Validating HTML...")
+check(
+    [
+        "java",
+        "-jar",
+        "../node_modules/vnu-jar/build/dist/vnu.jar",
+        "--filterfile",
+        "../tools/documentation.vnufilter",
+        "--skip-non-html",
+        "_build/html",
+    ]
+)
+
+if options.skip_check_links:
+    color_message("94", "Skipped testing links in documentation.")
+else:
+    os.chdir("../tools/documentation_crawler")
+    if options.skip_external_link_check:
+        color_message("94", "Testing only internal links in documentation...")
+        check(
+            [
+                "scrapy",
+                "crawl_with_status",
+                "documentation_crawler",
+                "-a",
+                "skip_external=set",
+                *options.loglevel,
+            ]
+        )
         # calling crawl directly as parameter needs to be passed
-    else
-        color_message 94 "Testing links in documentation..."
-        check scrapy crawl_with_status documentation_crawler "${loglevel[@]}"
-    fi
-fi
+    else:
+        color_message("94", "Testing links in documentation...")
+        check(["scrapy", "crawl_with_status", "documentation_crawler", *options.loglevel])
 
-exit "$err"
+
+sys.exit(err)