scripts/build_docs.py

#!/usr/bin/python


"""
build-docs.py

Version:        19 Oct 2023

Purpose:        Build the OSS Druid Docusaurus 2 docs for all
                versions supplied in the [-v, --versions] flag.
                Versions aside from "latest" only retain content
                from the docs folder. The "latest" version keeps
                everything. Assumes script is called from
                `druid-website-src/static/build-scripts` directory.

Help:           python build-docs.py --help

Example call:   python build-docs.py -v latest 26.0.0

"""

import fileinput
import os
import re
import shutil
import subprocess
import sys

def build_docs(versions, use_yarn):

    # define the folders that Docusaurus builds into and a temporary one
    build_dir = "build"
    temp_dir = "build__temp"

    for v in versions:
        print(f"Building the docs for version '{v}'...")

        # replace "latest" in redirects to the appropriate version
        if v != "latest":
            for line in fileinput.input("redirects.js", inplace=1):
                print(line.replace("/latest/", f"/{v}/"), end='')

        # set the version in "buildVersion" variable in docusaurus.config.js
        replacement = f'var buildVersion = "{v}";'
        for line in fileinput.input("docusaurus.config.js", inplace=1):
            print(re.sub(r"^var buildVersion.*", replacement, line), end='')

        # remove specific version folder in published_versions/docs if exists
        shutil.rmtree(f"published_versions/docs/{v}", ignore_errors=True)

        # build the docs
        if not use_yarn:
            subprocess.run(["npm", "run", "build"])
        else:
            subprocess.run(["yarn", "build"])

        # move output to temporary directory since docusaurus 2
        # overwrites build directory with each build.
        # the "latest" version is built last to maintain
        # all the non-docs content for latest
        if not os.path.isdir(build_dir):
            sys.exit("ERROR: The docs were not built. Check Docusaurus logs.")
        shutil.copytree(build_dir, temp_dir, dirs_exist_ok=True)

        # restore the redirect file back to URLs with "latest"
        #subprocess.run(["git", "restore", "redirects.js"])
        if v != "latest":
            for line in fileinput.input("redirects.js", inplace=1):
                print(line.replace(f"/{v}/", "/latest/"), end='')

        # save the assets folder to check into GitHub
        # applies to EACH version, since Doc2 attaches an alphanumeric string
        # to each asset; so you can't republish an old version unless you
        # also have the associated assets
        shutil.copytree(f"{build_dir}/assets", 'published_versions/assets', dirs_exist_ok=True)


    # after building ALL versions, rename the temp directory back to "build"
    shutil.rmtree(build_dir)
    shutil.move(temp_dir, build_dir)

    # save the final build output to check into GitHub
    print("Copying build output to ../published_versions. Use that directory to publish the site.")
    shutil.copytree(build_dir, 'published_versions', dirs_exist_ok=True)


def main(versions, skip_install, use_yarn):

    # from druid-website-src/scripts,
    # move to druid-website-src to run the npm commands
    os.chdir("../")

    # sort to build "latest" last
    versions = sorted(versions)

    # install docusaurus 2
    if not skip_install:
        print("Installing Docusaurus...")

        if not use_yarn:
            subprocess.run(["npm", "install"])
        else:
            subprocess.run(["yarn", "install"])

    # remove the old build directory
    shutil.rmtree('build', ignore_errors=True)

    # do the actual builds
    build_docs(versions, use_yarn)

if __name__ == "__main__":
    import argparse
    parser = argparse.ArgumentParser()

    parser.add_argument("-v", "--versions", required=True, nargs='+',
                        help="One or more versions to build. "
                        "For example: -v latest 26.0.0")

    parser.add_argument("--skip-install",
                        help="Skip the Docusaurus 2 installation",
                        action='store_true')

    parser.add_argument("--yarn", default=False,
                        help="Use yarn to install and build instead of npm",
                        action='store_true')

    args = parser.parse_args()

    main(args.versions, args.skip_install, args.yarn)