Docs: Add API Reference as top-level nav (#2180)

can either link to redoc hosted elsewhere or make a local copy: - for local frontend build, just redirect to http://localhost:30870/api/redoc - for deployment, make local copy: run copy-api-docs.sh, copy locally from prod and serve at /api/ - copy-api-docs.sh copies openapi.json, redoc and logo to /api/ dir - if analytics enabled, also injects analytics scripts - for local testing, run copy-api-docs.sh and then run mkdocs serve - ci: copy from prod server - fixes #1582
webrecorder · Nov 28, 2024 · 9911547 · 9911547
1 parent 661e5d9
commit 9911547
Show file tree

Hide file tree

Showing 5 changed files with 26 additions and 1 deletion.
diff --git a/.github/workflows/docs-publish.yaml b/.github/workflows/docs-publish.yaml
@@ -21,6 +21,12 @@ jobs:
       - name: Generate Helm Chart Index
         run: python ./scripts/generate-helm-index.py > ./frontend/docs/docs/helm-repo/index.yaml
 
+      - name: Copy Docs Files
+        run: frontend/docs/copy-api-docs.sh
+        env:
+          DOCS_SOURCE_URL: https://app.browsertrix.com
+          ENABLE_ANALYTICS: true
+
       - name: Build Docs
         run: cd frontend/docs; mkdocs gh-deploy --force
         env:

diff --git a/frontend/Dockerfile b/frontend/Dockerfile
@@ -44,7 +44,7 @@ RUN pip install mkdocs-material
 COPY --link ./docs/mkdocs.yml .
 COPY --link ./docs/docs ./docs
 
-RUN mkdocs build
+RUN API_DOCS_URL=/api/redoc mkdocs build
 
 FROM docker.io/library/nginx:1.23.2
 

diff --git a/frontend/docs/copy-api-docs.sh b/frontend/docs/copy-api-docs.sh
@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+CURR=$(dirname "${BASH_SOURCE[0]}")
+
+TARGET=$CURR/docs/api/
+mkdir $TARGET
+curl "$DOCS_SOURCE_URL/api/openapi.json" > $TARGET/openapi.json
+curl "$DOCS_SOURCE_URL/api/redoc" > $TARGET/index.html
+curl "$DOCS_SOURCE_URL/docs-logo.svg" > $TARGET/../docs-logo.svg
+
+if [ -n $ENABLE_ANALYTICS ]; then
+  SCRIPT_1='    <script defer data-domain=\"docs.browsertrix.com\" src=\"https://p.webrecorder.net/js/script.outbound-links.js\"></script>'
+  SCRIPT_2='    <script>window.plausible = window.plausible || function () { (window.plausible.q = window.plausible.q || []).push(arguments) }</script>'
+  awk "1;/<head>/{ print \"$SCRIPT_1\"; print \"$SCRIPT_2\" }" $TARGET/index.html > $TARGET/index.html.new
+  mv $TARGET/index.html.new $TARGET/index.html
+fi
diff --git a/frontend/docs/docs/index.md b/frontend/docs/docs/index.md
@@ -15,6 +15,7 @@ Docs are organized into the following sections:
 - [User Guide](./user-guide/index.md) — Instructions on how to use Browsertrix to create and share web archives.
 - [Self-Hosting](./deploy/index.md) — Instructions on how to install, set up, and deploy self-hosted Browsertrix.
 - [Development](./develop/index.md) — Contribute to the open source development of Browsertrix software.
+- [API Reference](/api) - Full API reference for interacting with the Browsertrix backend.
 
 If you have feedback on the docs, please feel free to [reach out to us](mailto:docs-feedback@webrecorder.net).
 

diff --git a/frontend/docs/mkdocs.yml b/frontend/docs/mkdocs.yml
@@ -91,6 +91,9 @@ nav:
       - develop/localization.md
       - develop/docs.md
 
+  - API Reference: !ENV [ API_DOCS_URL, "/api/" ]
+
+
 markdown_extensions:
   - toc:
       toc_depth: 3