From 56a03f9cfef4dca0d5989fc9cd69cb5c3d0c2b57 Mon Sep 17 00:00:00 2001 From: NixReaper Date: Sun, 6 Sep 2026 06:04:59 -0500 Subject: [PATCH] Add a public API wiki at /wiki Builds docs/ into a static site via mkdocs + mkdocs-material in its own Docker build stage (docs-builder), so mkdocs itself never ends up in the runtime image -- only the rendered HTML does, mounted at /wiki alongside the existing /docs OpenAPI schema (unconditionally, unlike /docs, since this is curated content meant to be public regardless of AURORA_API_DOCS_ENABLED). docs/aurora-core-spec.md (the internal build spec, referenced by "section N" comments throughout the codebase) is excluded from the built site entirely via exclude_docs, not just left out of the nav -- it was never meant for public consumption. Co-Authored-By: Claude Sonnet 5 --- .gitignore | 2 ++ app/main.py | 11 ++++++++++ docker/api.Dockerfile | 10 +++++++++ docs/api.md | 3 ++- docs/index.md | 33 ++++++++++++++++++++++++++++ mkdocs.yml | 51 +++++++++++++++++++++++++++++++++++++++++++ pyproject.toml | 4 ++++ 7 files changed, 113 insertions(+), 1 deletion(-) create mode 100644 docs/index.md create mode 100644 mkdocs.yml diff --git a/.gitignore b/.gitignore index 5d900e4..800063b 100644 --- a/.gitignore +++ b/.gitignore @@ -21,3 +21,5 @@ Thumbs.db .idea/ .vscode/ media_cache/ +site/ +/wiki/ diff --git a/app/main.py b/app/main.py index e1843bb..30d5a9a 100644 --- a/app/main.py +++ b/app/main.py @@ -94,6 +94,17 @@ app.mount( name="media", ) +# Public API documentation (mkdocs, built from docs/ -- see +# docker/api.Dockerfile's docs-builder stage and mkdocs.yml). Unlike /docs +# (the auto-generated OpenAPI schema, gated by AURORA_API_DOCS_ENABLED +# since it can reveal more raw internal detail), this is curated, +# intentionally public content -- always mounted regardless of that flag. +# The directory only exists in the built Docker image; ensure it's present +# so a local dev server that hasn't run `mkdocs build` doesn't crash on +# startup, same reasoning as MEDIA_ROOT above. +Path("wiki").mkdir(parents=True, exist_ok=True) +app.mount("/wiki", StaticFiles(directory="wiki", html=True), name="wiki") + @app.middleware("http") async def request_context_middleware( diff --git a/docker/api.Dockerfile b/docker/api.Dockerfile index f67b71d..1bec8ce 100644 --- a/docker/api.Dockerfile +++ b/docker/api.Dockerfile @@ -23,6 +23,15 @@ COPY app ./app # import string against the CWD regardless. RUN pip install --no-cache-dir -e . +# Builds the /wiki static site (mkdocs) in its own stage so mkdocs and its +# dependencies never end up in the runtime image -- only the rendered HTML +# does, copied in below. +FROM base AS docs-builder +RUN pip install --no-cache-dir mkdocs mkdocs-material +COPY mkdocs.yml ./ +COPY docs ./docs +RUN mkdocs build --strict -d /wiki_site + FROM base AS runtime RUN useradd --create-home --uid 1000 aurora COPY --from=builder /usr/local/lib/python3.12/site-packages /usr/local/lib/python3.12/site-packages @@ -30,6 +39,7 @@ COPY --from=builder /usr/local/bin /usr/local/bin COPY app ./app COPY migrations ./migrations COPY alembic.ini ./alembic.ini +COPY --from=docs-builder /wiki_site ./wiki # Owned by aurora *before* the volume mount happens — see worker.Dockerfile # for why (a fresh named volume otherwise defaults to root-owned, which the # non-root `aurora` user below can't write into). diff --git a/docs/api.md b/docs/api.md index fe1883d..49f2b8e 100644 --- a/docs/api.md +++ b/docs/api.md @@ -2,7 +2,8 @@ Base path: `/api/v1`. Interactive OpenAPI docs are available at `/docs` in any environment where `AURORA_API_DOCS_ENABLED=true` (default; set to -`false` to hide docs in production — section 32). +`false` to hide docs in production — section 32). This same document is +also published as a browsable page at `/wiki/api/` (see `mkdocs.yml`). All responses are JSON, built from Pydantic response schemas (`app/schemas/`), never from serialized ORM objects (section 18). Errors use diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..654b0d3 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,33 @@ +# Aurora Core + +Aurora Core is the metadata backend behind [AMDBS](https://www.amdbs.net) — a +TMDb/IMDb-style canonical data layer for movies, TV, people, and everything +that connects them. + +This wiki documents the public, read-only HTTP API. If you're building +against Aurora Core, start with the [API Reference](api.md). + +## Base URL + +``` +https://api.amdbs.net/api/v1 +``` + +All responses are JSON. Every entity has a stable, type-prefixed id (e.g. +`aur_movie_01m1q7p1c...`) — always use the id a response gave you rather +than constructing one yourself. + +## Interactive docs + +A live, explorable OpenAPI schema (Swagger UI) is available at +[`/docs`](/docs) alongside this wiki, when enabled in the current +environment. + +## Where to go next + +- **[API Reference](api.md)** — every endpoint, grouped by resource, with + query parameters and real example responses. +- **[Architecture](architecture.md)** — how Aurora Core is put together: + ingestion pipeline, caching, provider abstraction. +- **[Database](database.md)** — the schema itself, table by table. +- **[Entity relationships](erd.md)** — the same schema as a diagram. diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..5137aae --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,51 @@ +site_name: Aurora Core +site_description: API documentation for Aurora Core, the metadata backend behind AMDBS. +site_url: https://api.amdbs.net/wiki/ +docs_dir: docs +site_dir: site + +# The build spec is an internal planning document (build-phase instructions +# referenced by "section N" comments throughout app/), not documentation +# for API consumers -- excluded from the public wiki entirely rather than +# just left out of the nav (exclude_docs stops it from being copied into +# the built site at all, so it isn't reachable at a guessed URL either). +exclude_docs: | + aurora-core-spec.md + +nav: + - Home: index.md + - API Reference: api.md + - Architecture: architecture.md + - Database: database.md + - Entity relationships: erd.md + +theme: + name: material + palette: + - media: "(prefers-color-scheme: light)" + scheme: default + primary: indigo + toggle: + icon: material/weather-night + name: Switch to dark mode + - media: "(prefers-color-scheme: dark)" + scheme: slate + primary: indigo + toggle: + icon: material/weather-sunny + name: Switch to light mode + features: + - navigation.instant + - navigation.tracking + - navigation.top + - toc.follow + - content.code.copy + - search.suggest + +markdown_extensions: + - tables + - fenced_code + - toc: + permalink: true + - pymdownx.highlight + - pymdownx.superfences diff --git a/pyproject.toml b/pyproject.toml index 6f9983f..2566a23 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -41,6 +41,10 @@ dev = [ load = [ "locust>=2.31.0", ] +docs = [ + "mkdocs>=1.6.0", + "mkdocs-material>=9.5.0", +] [build-system] requires = ["setuptools>=68"]