From 68fcdaf1313a48ff45690d5ea142fb7a5694a8a0 Mon Sep 17 00:00:00 2001 From: Thomas Sibley Date: Tue, 20 Aug 2024 11:47:24 -0700 Subject: [PATCH 1/3] docs: Use envvar directive to attach semantics MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Among other things, this makes the var names linkable with :envvar:`…` and indexes them not just individually but also collectively under "Environment variables" so the index includes a single list of all documented vars. When I originally wrote this page, I didn't yet know about the envvar directive and role. I've since used it extensively in Nextstrain CLI's documentation, though. --- augur/utils.py | 2 +- docs/usage/envvars.rst | 6 ++++-- 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/augur/utils.py b/augur/utils.py index 5d28b6133..d794d2566 100644 --- a/augur/utils.py +++ b/augur/utils.py @@ -104,7 +104,7 @@ def write_json(data, file, indent=(None if os.environ.get("AUGUR_MINIFY_JSON") e file file path or handle to write to indent : int or None, optional - JSON indentation level. Default is `None` if the environment variable `AUGUR_MINIFY_JSON` + JSON indentation level. Default is `None` if the environment variable :envvar:`AUGUR_MINIFY_JSON` is truthy, else 1 include_version : bool, optional Include the augur version. Default: `True`. diff --git a/docs/usage/envvars.rst b/docs/usage/envvars.rst index 0a3a0bffd..f3985e10e 100644 --- a/docs/usage/envvars.rst +++ b/docs/usage/envvars.rst @@ -5,13 +5,15 @@ Environment variables Augur's behaviour can be globally modified by the values of some specific environment variables. These can be especially useful in the context of an entire pipeline or workflow which uses Augur, as the environment variables can be set once for all Augur commands at the start of the pipeline. -``AUGUR_MINIFY_JSON`` +.. envvar:: AUGUR_MINIFY_JSON + Boolean. If set to a non-empty value, all JSON output produced by Augur will be minified by omitting indentation and newlines. Minifying the JSON will substantially reduce file sizes, which is helpful for large, deeply nested trees. -``AUGUR_RECURSION_LIMIT`` +.. envvar:: AUGUR_RECURSION_LIMIT + Integer. If set to a non-empty value, the Python recursion limit will be set to the given value early in Augur's execution by calling :func:`sys.setrecursionlimit`. From 65ab80982e3e8fb1c62f399c1e450a9b512639d8 Mon Sep 17 00:00:00 2001 From: Thomas Sibley Date: Tue, 20 Aug 2024 11:52:25 -0700 Subject: [PATCH 2/3] =?UTF-8?q?docs:=20Move=20AUGUR=5FDEBUG=20definition?= =?UTF-8?q?=20to=20our=20env=20vars=20page=E2=80=A6?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit …instead of being buried in the developer API pages. Much more discoverable. Modifies formatting of the rST to match the new document's existing formatting, but the content is the same. Thanks to @joverlee521 for catching this misplacement in post-merge review.¹ ¹ --- augur/debug.py | 6 +----- docs/usage/envvars.rst | 7 +++++++ 2 files changed, 8 insertions(+), 5 deletions(-) diff --git a/augur/debug.py b/augur/debug.py index 9d36f1f82..02a5bbebf 100644 --- a/augur/debug.py +++ b/augur/debug.py @@ -1,11 +1,7 @@ """ Debug flags and utilities. -.. envvar:: AUGUR_DEBUG - - Set to a truthy value (e.g. 1) to print more information about (handled) - errors. For example, when this is not set or falsey, stack traces and - parent exceptions in an exception chain are omitted from handled errors. +See also :envvar:`AUGUR_DEBUG`. """ from os import environ diff --git a/docs/usage/envvars.rst b/docs/usage/envvars.rst index f3985e10e..4aacf2430 100644 --- a/docs/usage/envvars.rst +++ b/docs/usage/envvars.rst @@ -5,6 +5,13 @@ Environment variables Augur's behaviour can be globally modified by the values of some specific environment variables. These can be especially useful in the context of an entire pipeline or workflow which uses Augur, as the environment variables can be set once for all Augur commands at the start of the pipeline. +.. envvar:: AUGUR_DEBUG + + Boolean. + Set to a truthy value (e.g. 1) to print more information about (handled) errors. + + For example, when this is not set or falsey, stack traces and parent exceptions in an exception chain are omitted from handled errors. + .. envvar:: AUGUR_MINIFY_JSON Boolean. From 8c31208912d6b06bb1ce33fe9ff3fc7856914767 Mon Sep 17 00:00:00 2001 From: Thomas Sibley Date: Tue, 20 Aug 2024 12:39:14 -0700 Subject: [PATCH 3/3] docs: Improve AUGUR_DEBUG description Includes clarification of "a truthy value" as "a non-empty value", since all env vars values are strings and any non-empty string is a truthy value in Python. The new phrasing matches existing phrasing in our docs and makes it much clearer to a reader not thinking about details of Python's values. --- CHANGES.md | 2 +- docs/usage/envvars.rst | 5 +++-- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/CHANGES.md b/CHANGES.md index bb1bb8d5d..7ac015a76 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -6,7 +6,7 @@ * A new command, `augur merge`, now allows for generalized merging of two or more metadata tables. [#1563][] (@tsibley) * Two new commands, `augur read-file` and `augur write-file`, now allow external programs to do i/o like Augur by piping from/to these new commands. They provide handling of compression formats and newlines consistent with the rest of Augur. [#1562][] (@tsibley) -* A new debugging mode can be enabled by setting the `AUGUR_DEBUG` environment variable to `1` (or another truthy value). Currently the only effect is to print more information about handled (i.e. anticipated) errors. For example, stack traces and parent exceptions in an exception chain are normally omitted for handled errors, but setting this env var includes them. Future debugging and troubleshooting features, like verbose operation logging, will likely also condition on this new debugging mode. [#1577][] (@tsibley) +* A new debugging mode can be enabled by setting the `AUGUR_DEBUG` environment variable to `1` (or any non-empty value). Currently the only effect is to print more information about handled (i.e. anticipated) errors. For example, stack traces and parent exceptions in an exception chain are normally omitted for handled errors, but setting this env var includes them. Future debugging and troubleshooting features, like verbose operation logging, will likely also condition on this new debugging mode. [#1577][] (@tsibley) ### Bug Fixes diff --git a/docs/usage/envvars.rst b/docs/usage/envvars.rst index 4aacf2430..9f74677e9 100644 --- a/docs/usage/envvars.rst +++ b/docs/usage/envvars.rst @@ -8,9 +8,10 @@ These can be especially useful in the context of an entire pipeline or workflow .. envvar:: AUGUR_DEBUG Boolean. - Set to a truthy value (e.g. 1) to print more information about (handled) errors. + If set to a non-empty value, more detailed debugging information is shown by Augur during execution and handling of errors. - For example, when this is not set or falsey, stack traces and parent exceptions in an exception chain are omitted from handled errors. + For example, when this is enabled, stack traces and parent exceptions in an exception chain are no longer omitted from handled (i.e. expected) errors. + Some commands will also emit more verbose operation logging during their execution. .. envvar:: AUGUR_MINIFY_JSON