docs: generate the ODYSSEUS_* configuration reference from the source

The configuration surface was undiscoverable. .env.example has three active
lines, and of the ODYSSEUS_* variables the code actually reads, most appear
nowhere in .env.example, docs/, website/ or README.md - including several that
change security-relevant behaviour (ODYSSEUS_BROWSER_NO_SANDBOX,
ODYSSEUS_ALLOW_PRIVATE_CALDAV, ODYSSEUS_ENABLE_HOST_DOCKER,
ODYSSEUS_MCP_ALLOWED_COMMANDS). Every question about one of them lands in the
issue tracker.

A hand-written page would drift within a month, so the page is generated:

- scripts/generate_env_reference.py walks the Python sources, collects each read
  with the default it falls back to and the file it is read in, groups by area,
  and marks the internal variables rather than omitting them.
- website/configuration-reference.md is the generated output, wired into the
  Pages layout and linked from setup.md and .env.example. .env.example stays a
  short deployment-level example and links onward rather than growing.
- tests/test_env_reference.py regenerates and compares, so adding a variable
  without documenting it fails the suite. That is the point: the current state
  happened because nothing objected.

Finding the reads needs more than one pattern. Two families - the upload caps in
src/upload_limits.py and the media-ingress overrides in src/media_ingress.py -
are read through helper functions, so the generator detects env-reader helpers
rather than hardcoding a list. Others span two lines, hold the variable name in
a module constant, or read through a mapping passed in as an argument. One lives
inside a string literal, in the Ollama probe script routes/cookbook_helpers.py
builds line by line. A line-based grep for os.environ.get("ODYSSEUS_ finds 70 of
the 98 the generator finds; the page reports that gap and recomputes it on every
run so the claim cannot go stale.

No application behaviour changes.
This commit is contained in:
Léo
2026-09-30 15:11:19 +02:00
parent 6105702901
commit 5c8611fba6
6 changed files with 1586 additions and 0 deletions
+5
View File
@@ -1,5 +1,10 @@
# Odysseus UI — Environment Configuration
# Copy this file to .env and fill in your values.
#
# This file stays deliberately short: it is for deployment-level overrides, and
# most runtime configuration belongs in Settings inside the app. For the complete
# list of ODYSSEUS_* variables the code reads, with the default each one falls
# back to, see website/configuration-reference.md (generated from the source).
# ============================================================
# LLM Configuration