Frontend hosted-docs (#2107)

Fixes #2106 

Docs are now hosted as part of the frontend at `/docs` by default.

- If `docs_url` is set in the helm chart, the `/docs` endpoint will
redirect to that endpoint instead
- Use multi-stage python image to build mkdocs as part of frontend, then
copy static output
- Dir layout: mkdocs.yml and docs into frontend/docs
- CI: Update docs build GH action to use new path
- Update all frontend paths to use `/docs/` instead of
`https://docs.browsertrix.com/`

---------
Co-authored-by: Henry Wilkinson <[email protected]>

.github/workflows/docs-publish.yaml

@@ -19,6 +19,6 @@ jobs:
       - run: pip install mkdocs-material requests pyyaml
 
       - name: Generate Helm Chart Index
-        run: python ./scripts/generate-helm-index.py > ./docs/helm-repo/index.yaml
+        run: python ./scripts/generate-helm-index.py > ./frontend/docs/docs/helm-repo/index.yaml
 
-      - run: mkdocs gh-deploy --force
+      - run: cd frontend/docs; mkdocs gh-deploy --force

chart/templates/frontend.yaml

@@ -49,6 +49,11 @@ spec:
             - name: RWP_BASE_URL
               value: {{ .Values.rwp_base_url }}
 
+            {{- if .Values.docs_url }}
+            - name: DOCS_URL
+              value: {{ .Values.docs_url }}
+            {{- end }}
+
             {{- if .Values.minio_local }}
             - name: LOCAL_MINIO_HOST
               value: "{{ .Values.minio_host }}"

chart/values.yaml

@@ -156,6 +156,11 @@ local_service_port: 30870
 
 frontend_alias: "http://browsertrix-cloud-frontend"
 
+# custom URL for where Browsertrix docs are hosted
+# by default, docs are served from /docs/ but can be served from a custom
+# URL specified here.
+# docs_url: "https://browsertrix-docs.example.com/"
+
 # Autoscaling
 # -----------
 # max number of backend pods to scale to

frontend/.eslintrc.js

@@ -138,7 +138,7 @@ module.exports = {
       typescript: true,
     },
   },
-  ignorePatterns: ["__generated__", "__mocks__", "dist"],
+  ignorePatterns: ["__generated__", "__mocks__", "dist", "docs"],
   overrides: [
     {
       extends: ["plugin:@typescript-eslint/disable-type-checked"],

frontend/.prettierignore

@@ -2,3 +2,4 @@ __generated__
 __mocks__
 assets
 dist
+docs

frontend/Dockerfile

@@ -35,10 +35,23 @@ ENV GIT_COMMIT_HASH=${GIT_COMMIT_HASH} \
 RUN yarn build && \
   rm -rf ./node_modules
 
+FROM --platform=$BUILDPLATFORM docker.io/library/python:3.12-slim as build_docs
+
+WORKDIR /docs
+
+RUN pip install mkdocs-material
+
+COPY --link ./docs/mkdocs.yml .
+COPY --link ./docs/docs ./docs
+
+RUN mkdocs build
+
 FROM docker.io/library/nginx:1.23.2
 
 COPY --link --from=build_deps /app/dist /usr/share/nginx/html
 
+COPY --link --from=build_docs /docs/site /usr/share/nginx/html/docs
+
 #COPY ./nginx.conf /etc/nginx/nginx.conf
 COPY --link ./frontend.conf.template /etc/nginx/templates/
 COPY --link ./minio.conf /etc/nginx/includes/

frontend/docs/.gitignore

@@ -0,0 +1 @@
+site

docs/js/insertversion.js → frontend/docs/docs/js/insertversion.js

@@ -25,9 +25,7 @@ function parseVersion(string) {
           node.nodeValue = node.nodeValue.replaceAll("VERSION", version);
         }
       });
-    } catch (e) {
-
-    }
+    } catch (e) {}
   }
 }
 

frontend/docs/docs/overrides/main.html

@@ -0,0 +1,2 @@
+{% extends "base.html" %} {% block icons %} {% set icon_path =
+"overrides/.icons/bootstrap/" %} {{ super() }} {% endblock %}