From 99115473e5df3931f1cbdba2631de884d970c1d0 Mon Sep 17 00:00:00 2001 From: Ilya Kreymer Date: Wed, 27 Nov 2024 17:00:54 -0800 Subject: [PATCH] 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 --- .github/workflows/docs-publish.yaml | 6 ++++++ frontend/Dockerfile | 2 +- frontend/docs/copy-api-docs.sh | 15 +++++++++++++++ frontend/docs/docs/index.md | 1 + frontend/docs/mkdocs.yml | 3 +++ 5 files changed, 26 insertions(+), 1 deletion(-) create mode 100755 frontend/docs/copy-api-docs.sh diff --git a/.github/workflows/docs-publish.yaml b/.github/workflows/docs-publish.yaml index dc73967f93..a83d6a98bc 100644 --- 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 index 6b115f3262..21cd324b45 100644 --- 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 new file mode 100755 index 0000000000..a3d373ee68 --- /dev/null +++ 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_2=' ' + awk "1;//{ 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 index 1bd65465fb..1b194ce8ed 100644 --- 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 index 7eb9381df4..bb65327485 100644 --- 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