Document the workspace level env stanza

Signed-off-by: Rudi Grinberg <[email protected]>

CHANGES.md

@@ -5,6 +5,10 @@ next
   passing in `--root` in conjunction with `--workspace` or `--config` would not
   work correctly (#997, @rgrinberg)
 
+- Add support for customizing env nodes in workspace files. The `env` stanza is
+  now allowed in toplevel position in the workspace file, or for individual
+  contexts. This feature requires `(dune lang 1.1)` (#1038, @rgrinberg)
+
 1.0.1 (19/07/2018)
 ------------------
 

doc/usage.rst

@@ -379,6 +379,13 @@ The build profile can be selected in the ``dune-workspace`` file by write a
 
 Note that the command line option ``--profile`` has precedence over this stanza.
 
+env
+~~~
+
+The ``env`` stanza can be used to set the base environment for all contexts in
+this workspace. This environment has the lowest precedence of all other ``env``
+stanzas. The syntax for this stanza is the same dune's :ref:`dune-env` stanza.
+
 context
 ~~~~~~~
 
@@ -407,6 +414,10 @@ context or can be the description of an opam switch, as follows:
   context. This has precedence over the command line option
   ``--profile``
 
+- ``(env <env>)`` to set the environment for a particular context. This is of
+  higher precedence than the toplevel ``env`` stanza in the workspace file. This
+  field the same options as the :ref:`dune-env` stanza.
+
 Both ``(default ...)`` and ``(opam ...)`` accept a ``targets`` field in order to
 setup cross compilation. See :ref:`advanced-cross-compilation` for more
 information.