From 6c00b106185776c0dbded131d080d84acaa5fff3 Mon Sep 17 00:00:00 2001 From: cproudlock Date: Sun, 20 Sep 2026 09:06:59 -0400 Subject: [PATCH] Ship the API docs the container never had, and theme them like the product /api/docs was broken in every Docker deployment, including the air-gapped ones. docs.py resolves openapi.json and llms.txt from the repo root, and the image copies shopdb, plugins, migrations, scripts and wsgi.py but never docs. The page rendered the Redoc shell and then answered 404 fetching its own specification. Only the two files the app actually serves are copied; the rest of that tree is prose with no business in a runtime image. The theme was invented colours that matched nothing. It now maps the product's own tokens, and reads the theme the way the app does: the application stores an explicit light/dark choice and stamps data-theme, so choosing light on a dark-desktop kiosk used to give a dark documentation page. The operating system setting is the fallback, exactly as it is in the app. Light-mode primary, success and error are a shade darker than the product tokens, because those tokens are designed as fills and fail contrast as text on the nested panels where type names and required labels sit. Measured with a browser harness rather than judged by eye: every text node in both themes now clears WCAG AA, from an initial 5603 reported failures - most of which were the harness itself ignoring alpha, which is its own lesson about trusting a number. Four Redoc elements carry hardcoded colours with no theme key and keep targeted rules, selected by tag and attribute rather than by generated class hashes that change on every build. The build now compiles the Python. Docker never imports the application, so a syntax error sails through every layer and surfaces as a crash-looping container; that happened, four restarts, while working on this file. Redoc's upstream licence file was never vendored although its bundle header points at it. The placeholder added here says exactly that rather than inventing the third-party notices it is supposed to carry, and the dead redocly.com badge is hidden: the licence wants the notice in the distribution, not a rendered link that a site with no internet cannot follow. --- Dockerfile | 14 ++ shopdb/core/api/docs.py | 180 ++++++++++++++---- .../redoc.standalone.js.LICENSE.txt | 37 ++++ tests/test_core/test_api_docs_tryit.py | 8 +- 4 files changed, 206 insertions(+), 33 deletions(-) create mode 100644 shopdb/core/api/staticdocs/redoc.standalone.js.LICENSE.txt diff --git a/Dockerfile b/Dockerfile index f8b7cf04..9eeb7f1f 100644 --- a/Dockerfile +++ b/Dockerfile @@ -124,6 +124,20 @@ COPY migrations/ ./migrations/ COPY scripts/ ./scripts/ COPY wsgi.py ./ +# The two files under docs/ that the APP SERVES at runtime, not documentation. +# shopdb/core/api/docs.py resolves both relative to the repo root, so without +# them /api/docs renders the Redoc shell and then 404s fetching its own spec - +# which is what every Docker deployment did. Copied by name rather than copying +# docs/ wholesale: the rest of that tree is prose and has no business in a lean +# runtime image. +COPY docs/openapi.json docs/llms.txt ./docs/ + +# Fail the BUILD on a syntax error rather than the pod at runtime. Docker never +# imports the application, so a broken .py sails through every layer and only +# surfaces as a crash-looping container: observed, four restarts before anyone +# noticed. compileall touches nothing at runtime and costs a couple of seconds. +RUN python -m compileall -q shopdb plugins migrations wsgi.py + # Built SPA from stage 1. Flask serves it via register_frontend_routes. COPY --from=frontendbuild /build/frontend/dist ./frontend/dist diff --git a/shopdb/core/api/docs.py b/shopdb/core/api/docs.py index cbda186b..f2a5be59 100644 --- a/shopdb/core/api/docs.py +++ b/shopdb/core/api/docs.py @@ -97,50 +97,162 @@ def docs_index(): '' '' '' '%s' '
' '' '' '' % (tryit_note, redoc_url, json.dumps(spec_url)) ) @@ -224,7 +336,11 @@ def swagger_tryit(): '' '' '' '' diff --git a/shopdb/core/api/staticdocs/redoc.standalone.js.LICENSE.txt b/shopdb/core/api/staticdocs/redoc.standalone.js.LICENSE.txt new file mode 100644 index 00000000..8e040433 --- /dev/null +++ b/shopdb/core/api/staticdocs/redoc.standalone.js.LICENSE.txt @@ -0,0 +1,37 @@ +Redoc (redoc.standalone.js) - vendored third-party bundle +========================================================= + +Redoc is distributed under the MIT License. + +WHY THIS FILE IS A PLACEHOLDER +------------------------------ +The vendored bundle opens with: + + /*! For license information please see redoc.standalone.js.LICENSE.txt */ + +That companion file is produced by webpack and carries the extracted licence +headers of Redoc AND of every third-party package compiled into the bundle. It +ships alongside redoc.standalone.js in the upstream dist and was not copied when +this bundle was vendored, so the pointer above led nowhere. + +The contents are NOT reproduced from memory here, because doing so would mean +inventing attribution for packages whose notices cannot be read back out of a +minified bundle. Do not treat this file as a substitute for the real one. + +WHAT TO DO +---------- +When next re-vendoring Redoc, copy BOTH files out of the upstream dist: + + redoc.standalone.js + redoc.standalone.js.LICENSE.txt <- replaces this placeholder + +and record the version and source URL in the same commit, so the next person +does not have to work out what is installed by reading the minified source. + +The version of the currently vendored bundle could not be determined: it has no +version string, and no commit or document in this repository records it. + +RELATED +------- +Swagger UI is vendored in this same directory and DOES carry its upstream +notice (swagger-ui.LICENSE.txt). That is the pattern this file should follow. diff --git a/tests/test_core/test_api_docs_tryit.py b/tests/test_core/test_api_docs_tryit.py index 44b07933..93b7cc3e 100644 --- a/tests/test_core/test_api_docs_tryit.py +++ b/tests/test_core/test_api_docs_tryit.py @@ -266,7 +266,13 @@ def test_the_redoc_page_follows_the_system_theme(client): assert 'Redoc.init' in page assert '