Document the Docker environment variables the applications read (#3387) - #3420
Merged
Conversation
docs/source/docker.rst told users to set TARGET_MANAGER_BACKEND, which no application reads, with a value which has no scheme. Following the quickstart exactly left the VWS and VWQ containers permanently unhealthy: the health check probe constructs VWSSettings, which raises when target_manager_base_url is unset. Use TARGET_MANAGER_BASE_URL and http://vuforia-target-manager-mock:5000, document RESPONSE_DELAY_SECONDS and the three host variables the images set, and show the full response body which the target manager returns for a created cloud database. The console blocks in the documentation are checked for valid shell but never run, so nothing caught the drift. Add tests which compare the documented variables against the settings fields of the three applications, and the required section against the fields with no default. Closes #3387 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Comparing the prose in docker.rst against the settings classes with a regular expression is a weak way to keep the two together. The documentation is corrected either way; keeping it correct belongs in a Sphinx extension which generates it, which is being packaged separately. Also drop the three host variables, which were documented only so that the tests could require full coverage of the settings fields. The images set them and they are not configuration for users of the images. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Each setting is now described with Field(description=...) where it is defined, and docs/source/settings_envvars.py turns those descriptions into the envvar entries in the configuration reference, in the same way that the endpoints on the same page come from autoflask. The extension also defines a |env-<name>| substitution per variable, so the example docker run commands name variables which cannot be stale either, and rejects a substitution which survives into a page, which is what sphinx-substitution-extensions does with an undefined one in a code block. Four kinds of drift now fail the documentation build: a variable named in the documentation which nothing reads, a renamed setting, a new setting with no description, and a settings class which the configuration names but which does not exist. The extension takes the settings classes and the fields to leave undocumented from conf.py and imports nothing from this project, so it can move to a package of its own. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
…ings" This reverts commit b041b29. Generating the reference from the settings classes lost the grouping by container, which is the question a reader of this page has: not "what reads TARGET_RATER" but "what do I set on the target manager container". A "Read by ..." line at the end of each entry carries the same information but only to someone who reads every entry. The documentation is written by hand, grouped by container as before, with the corrected variable names and values.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
docs/source/docker.rsttold users to setTARGET_MANAGER_BACKEND, which no application reads, with a value which has no scheme.Following the quickstart exactly leaves the VWS and VWQ containers permanently unhealthy: the health check probe goes through
validate_request, which constructsVWSSettings, which raises whiletarget_manager_base_urlis unset.TARGET_MANAGER_BASE_URLandhttp://vuforia-target-manager-mock:5000in the four places the old name appeared.RESPONSE_DELAY_SECONDS, which both the VWS and Query apps read, under a heading for the two containers which read it.POST /cloud_databasesresponse body, taken from a real response rather than hand-written.Documentation only; no behaviour change, no new tests and no new automation.
Closes #3387
🤖 Generated with Claude Code