From 3eaac219a58b2270bea3faceacb0f42f4775fe89 Mon Sep 17 00:00:00 2001 From: Ilya Kreymer Date: Sat, 23 Nov 2024 23:12:24 -0800 Subject: [PATCH] add an 'API Reference' top level nav in docs: - for local build, just point to http://localhost:30870/api/redoc - for deployment, copy locally from prod and serve at /api/ - add copy-api-docs.sh to copy openapi.json, redoc and logo to /api/ dir - for local testing, run copy-api-docs.sh and then run mkdocs serve - fixes #1582 --- .github/workflows/docs-publish.yaml | 5 +++++ frontend/Dockerfile | 2 +- frontend/docs/copy-api-docs.sh | 8 ++++++++ frontend/docs/docs/index.md | 1 + frontend/docs/mkdocs.yml | 3 +++ 5 files changed, 18 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..34902177ce 100644 --- a/.github/workflows/docs-publish.yaml +++ b/.github/workflows/docs-publish.yaml @@ -21,6 +21,11 @@ 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 + - 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..db25383010 --- /dev/null +++ b/frontend/docs/copy-api-docs.sh @@ -0,0 +1,8 @@ +#!/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 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