tea/browsertrix
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

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

Browse Source 
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
This commit is contained in:
Ilya Kreymer 2024-11-27 17:00:54 -08:00 committed by GitHub
parent 661e5d9fae
commit 99115473e5
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
5 changed files with 26 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
.github/workflows/docs-publish.yaml vendored
View File

@ -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:

2
frontend/Dockerfile
View File

@ -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

15
frontend/docs/copy-api-docs.sh Executable file
View File

@ -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

1
frontend/docs/docs/index.md
View File

@ -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).

3
frontend/docs/mkdocs.yml
View File

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