Move environment variables to a configuration file (#269)

Co-authored-by: Adam Turner <[email protected]>

Author: ewdurbin

build_docs.py

@@ -5,6 +5,26 @@
 Without any arguments builds docs for all active versions and
 languages.
 
+Environment variables for:
+
+- `SENTRY_DSN` (Error reporting)
+- `FASTLY_SERVICE_ID` / `FASTLY_TOKEN` (CDN purges)
+- `PYTHON_DOCS_ENABLE_ANALYTICS` (Enable Plausible for online docs)
+
+are read from the site configuration path for your platform
+(/etc/xdg/docsbuild-scripts on linux) if available,
+and can be overriden by writing a file to the user config dir
+for your platform ($HOME/.config/docsbuild-scripts on linux).
+The contents of the file is parsed as toml:
+
+```toml
+[env]
+SENTRY_DSN = "https://[email protected]/69420"
+FASTLY_SERVICE_ID = "deadbeefdeadbeefdead"
+FASTLY_TOKEN = "secureme!"
+PYTHON_DOCS_ENABLE_ANALYTICS = "1"
+```
+
 Languages are stored in `config.toml` while versions are discovered
 from the devguide.
 
@@ -48,6 +68,7 @@
 import tomlkit
 import urllib3
 import zc.lockfile
+from platformdirs import user_config_path, site_config_path
 
 TYPE_CHECKING = False
 if TYPE_CHECKING:
@@ -906,6 +927,7 @@ def main():
     """Script entry point."""
     args = parse_args()
     setup_logging(args.log_directory, args.select_output)
+    load_environment_variables()
 
     if args.select_output is None:
         build_docs_with_lock(args, "build_docs.lock")
@@ -1022,6 +1044,31 @@ def setup_logging(log_directory: Path, select_output: str | None):
     logging.getLogger().setLevel(logging.DEBUG)
 
 
+def load_environment_variables() -> None:
+    _user_config_path = user_config_path("docsbuild-scripts")
+    _site_config_path = site_config_path("docsbuild-scripts")
+    if _user_config_path.is_file():
+        ENV_CONF_FILE = _user_config_path
+    elif _site_config_path.is_file():
+        ENV_CONF_FILE = _site_config_path
+    else:
+        logging.info(
+            "No environment variables configured. "
+            f"Configure in {_site_config_path} or {_user_config_path}."
+        )
+        return
+
+    logging.info(f"Reading environment variables from {ENV_CONF_FILE}.")
+    if ENV_CONF_FILE == _site_config_path:
+        logging.info(f"You can override settings in {_user_config_path}.")
+    elif _site_config_path.is_file():
+        logging.info(f"Overriding {_site_config_path}.")
+    with open(ENV_CONF_FILE, "r") as f:
+        for key, value in tomlkit.parse(f.read()).get("env", {}).items():
+            logging.debug(f"Setting {key} in environment.")
+            os.environ[key] = value
+
+
 def build_docs_with_lock(args: argparse.Namespace, lockfile_name: str) -> int:
     try:
         lock = zc.lockfile.LockFile(HERE / lockfile_name)

requirements.txt

@@ -1,4 +1,5 @@
 jinja2
+platformdirs
 sentry-sdk>=2
 tomlkit>=0.13
 urllib3>=2