Merge branch 'trs/document-AUGUR_DEBUG'

Author: tsibley

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
 

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
 

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`.

docs/usage/envvars.rst

@@ -5,13 +5,23 @@ 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_DEBUG
+
+    Boolean.
+    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 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
+
     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`.