documentation: redoc -> scalar

.github/workflows/build-test-doc_upload.yaml

@@ -5,14 +5,22 @@ on:
     branches:
       - main
   pull_request:
+    types: [opened, reopened, synchronize, ready_for_review]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 permissions:
   contents: write
 jobs:
   build-test-doc:
     runs-on: ubuntu-latest
     timeout-minutes: 20
-    steps:
 
+    if: github.repository_owner == 'fritz-marshal' && github.event.pull_request.draft == false
+
+    steps:
     - uses: actions/checkout@v4
       with:
         submodules: recursive
@@ -25,18 +33,38 @@ jobs:
       with:
         node-version: 20
 
-    - uses: actions/cache@v2
+    - uses: actions/cache@v4
       with:
         path: |
           ~/.npm
         key: ${{ runner.os }}-npm-${{ hashFiles('package.json') }}
 
-    - uses: actions/cache@v2
+    - uses: actions/cache@v4
       with:
         path: |
           ~/.cache/pip
         key: ${{ runner.os }}-${{ hashFiles('**/requirements*.txt') }}
 
+    # caching dustmap & sncosmo files is dependent on their corresponding
+    # python package versions, so we use that as the cache key
+    - uses: actions/cache@v4
+      with:
+        path: |
+          persistentdata/dustmap/sfd
+        key: ${{ runner.os }}-dustmap-${{ hashFiles('**/requirements*.txt') }}
+        restore-keys: |
+          ${{ runner.os }}-dustmap-${{ hashFiles('**/requirements*.txt') }}
+          ${{ runner.os }}-dustmap-
+
+    - uses: actions/cache@v4
+      with:
+        path: |
+          ~/.astropy/cache/sncosmo/bandpasses
+        key: ${{ runner.os }}-sncosmo-${{ hashFiles('**/requirements*.txt') }}
+        restore-keys: |
+          ${{ runner.os }}-sncosmo-${{ hashFiles('**/requirements*.txt') }}
+          ${{ runner.os }}-sncosmo-
+
     - name: Install system dependencies
       run: |
         sudo apt update -y && sudo apt install -y libcurl4-gnutls-dev libgnutls28-dev

launcher/commands/doc.py

@@ -1,11 +1,58 @@
 import subprocess
 import os
 import json
+import jinja2
 
 from launcher.config import check_config
 from launcher.skyportal import patch as patch_skyportal
 
 
+def patch_api_doc_template():
+    """Patch the API documentation template with the OpenAPI spec.
+
+    This function reads the OpenAPI specification from the openapi.json file,
+    populates it with server information from the configuration, and renders
+    a HTML documentation page from https://github.com/scalar/scalar
+    using a Jinja2 template.
+
+    Raises:
+        ValueError: If the server information is not valid.
+    """
+    # open the openapi.json file generated by build-spec.py
+    from baselayer.app.env import load_env
+
+    _, cfg = load_env()
+
+    with open("openapi.json") as f:
+        openapi_spec = json.load(f)
+
+    # populate the OpenAPI spec with (optional) server information
+    servers = cfg.get("docs.servers", [])
+    if servers is None:
+        servers = []
+    if not isinstance(servers, list):
+        raise ValueError("API servers must be a list.")
+
+    for server in servers:
+        if not all(k in server for k in ("url", "description")):
+            raise ValueError("Each server must have 'url' and 'description' keys.")
+    openapi_spec["servers"] = servers
+
+    # Create a Jinja2 template environment
+    template_env = jinja2.Environment(loader=jinja2.FileSystemLoader(searchpath="./"))
+
+    # Load the template file
+    template = template_env.get_template("skyportal/doc/openapi.html.template")
+
+    # Render the template with the OpenAPI spec
+    output = template.render(openapi_spec=json.dumps(openapi_spec, indent=2))
+
+    # Write the output to a new HTML file
+    os.makedirs("./doc/_build/html", exist_ok=True)
+    with open("./doc/_build/html/api.html", "w") as f:
+        f.write(output)
+
+
 def doc(yes: bool = False, upload: bool = False):
     """Build the documentation
 
@@ -43,27 +90,12 @@ def doc(yes: bool = False, upload: bool = False):
             "servers": [{"url": "https://fritz.science"}],
         },
     )
-    with open("skyportal/openapi.json", "w") as f:
+    with open("openapi.json", "w") as f:
         json.dump(spec.to_dict(), f)
 
-    subprocess.run(
-        [
-            "npx",
-            "redoc-cli@0.13.21",
-            "bundle",
-            "openapi.json",
-            "--title",
-            "Fritz API docs",
-            "--cdn",
-            "--options.theme.logo.gutter",
-            "2rem",
-            "-o",
-            "../doc/_build/html/api.html",
-        ],
-        check=True,
-        cwd="skyportal",
-    )
-    os.remove("skyportal/openapi.json")
+    patch_api_doc_template()
+
+    os.remove("openapi.json")
 
     if upload:
         subprocess.run(