From 68fcdaf1313a48ff45690d5ea142fb7a5694a8a0 Mon Sep 17 00:00:00 2001 From: Thomas Sibley Date: Tue, 20 Aug 2024 11:47:24 -0700 Subject: [PATCH] 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`.