From 32f4a931bca767ec77fa66c73817ee78900a2a11 Mon Sep 17 00:00:00 2001 From: Ee Durbin Date: Fri, 11 Apr 2025 14:09:17 -0400 Subject: [PATCH 1/4] move environment vars to a configuration file ref #266 --- build_docs.py | 41 +++++++++++++++++++++++++++++++++++++++++ requirements.txt | 1 + 2 files changed, 42 insertions(+) diff --git a/build_docs.py b/build_docs.py index d4578eb..69785c8 100755 --- a/build_docs.py +++ b/build_docs.py @@ -5,6 +5,22 @@ 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: + +[env] +SENTRY_DSN = "https://0a0a0a0a0a0a0a0a0a0a0a@sentry.io/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 +64,31 @@ import tomlkit import urllib3 import zc.lockfile +from platformdirs import user_config_path, site_config_path + +ENV_CONF_FILE = 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 + +if ENV_CONF_FILE: + print(f"Reading environment variables from {ENV_CONF_FILE}") + if ENV_CONF_FILE == _site_config_path: + print(f"You can override settings in {_user_config_path}") + elif _site_config_path.is_file(): + print(f"Overriding {_site_config_path}") + with open(ENV_CONF_FILE, "r") as f: + for key, value in tomlkit.parse(f.read()).get("env", {}).items(): + print(f"Setting {key} in environment") + os.environ[key] = value +else: + print( + "No environment variables configured. " + f"Configure in {_site_config_path} or {_user_config_path}" + ) TYPE_CHECKING = False if TYPE_CHECKING: diff --git a/requirements.txt b/requirements.txt index 0cac810..535b36a 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,4 +1,5 @@ jinja2 +platformdirs sentry-sdk>=2 tomlkit>=0.13 urllib3>=2 From 6325e5c685fa9c2f68db7ea9d1b825d5d11da579 Mon Sep 17 00:00:00 2001 From: Ee Durbin Date: Fri, 11 Apr 2025 14:17:16 -0400 Subject: [PATCH 2/4] Apply suggestions from code review Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com> --- build_docs.py | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/build_docs.py b/build_docs.py index 69785c8..d740025 100755 --- a/build_docs.py +++ b/build_docs.py @@ -6,20 +6,24 @@ languages. Environment variables for: - - SENTRY_DSN (Error reporting) - - FASTLY_SERVICE_ID/FASTLY_TOKEN (CDN purges) - - PYTHON_DOCS_ENABLE_ANALYTICS (enable plausible for online docs) + +- `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://0a0a0a0a0a0a0a0a0a0a0a@sentry.io/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. From cd081deb16fa1a41d045559dc49d28a773009522 Mon Sep 17 00:00:00 2001 From: Ee Durbin Date: Fri, 11 Apr 2025 14:19:19 -0400 Subject: [PATCH 3/4] move configuration handling into main, for logging --- build_docs.py | 48 ++++++++++++++++++++++++------------------------ 1 file changed, 24 insertions(+), 24 deletions(-) diff --git a/build_docs.py b/build_docs.py index d740025..82f2689 100755 --- a/build_docs.py +++ b/build_docs.py @@ -70,30 +70,6 @@ import zc.lockfile from platformdirs import user_config_path, site_config_path -ENV_CONF_FILE = 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 - -if ENV_CONF_FILE: - print(f"Reading environment variables from {ENV_CONF_FILE}") - if ENV_CONF_FILE == _site_config_path: - print(f"You can override settings in {_user_config_path}") - elif _site_config_path.is_file(): - print(f"Overriding {_site_config_path}") - with open(ENV_CONF_FILE, "r") as f: - for key, value in tomlkit.parse(f.read()).get("env", {}).items(): - print(f"Setting {key} in environment") - os.environ[key] = value -else: - print( - "No environment variables configured. " - f"Configure in {_site_config_path} or {_user_config_path}" - ) - TYPE_CHECKING = False if TYPE_CHECKING: from collections.abc import Iterator, Sequence, Set @@ -952,6 +928,30 @@ def main(): args = parse_args() setup_logging(args.log_directory, args.select_output) + ENV_CONF_FILE = 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 + + if ENV_CONF_FILE: + 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 + else: + logging.info( + "No environment variables configured. " + f"Configure in {_site_config_path} or {_user_config_path}" + ) + if args.select_output is None: build_docs_with_lock(args, "build_docs.lock") elif args.select_output == "no-html": From 78a70a79ec1bc776b580082d638f074ab29fddc0 Mon Sep 17 00:00:00 2001 From: Adam Turner <9087854+aa-turner@users.noreply.github.com> Date: Fri, 11 Apr 2025 19:46:27 +0100 Subject: [PATCH 4/4] Factor out to `load_environment_variables()` --- build_docs.py | 50 ++++++++++++++++++++++++++------------------------ 1 file changed, 26 insertions(+), 24 deletions(-) diff --git a/build_docs.py b/build_docs.py index 82f2689..22fc5bd 100755 --- a/build_docs.py +++ b/build_docs.py @@ -927,30 +927,7 @@ def main(): """Script entry point.""" args = parse_args() setup_logging(args.log_directory, args.select_output) - - ENV_CONF_FILE = 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 - - if ENV_CONF_FILE: - 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 - else: - logging.info( - "No environment variables configured. " - f"Configure in {_site_config_path} or {_user_config_path}" - ) + load_environment_variables() if args.select_output is None: build_docs_with_lock(args, "build_docs.lock") @@ -1067,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)