Repair documentation of environment variables (#329)

* Repair documentation of environment variables * Additional docs suggested by @mattwthompson
openforcefield · Feb 29, 2024 · cccf7da · cccf7da
1 parent 032fc35
commit cccf7da
Show file tree

Hide file tree

Showing 3 changed files with 19 additions and 5 deletions.
diff --git a/docs/getting-started/bespoke-cli.md b/docs/getting-started/bespoke-cli.md
@@ -11,6 +11,8 @@ openff-bespoke --help
 openff-bespoke executor launch --help
 ```
 
+The executor can also be configured via [environment variables.](envvars)
+
 See the [quick start](quick_start_chapter) guide for examples of using the CLI.
 
 (cli_ref)=

diff --git a/docs/users/bespoke-executor.md b/docs/users/bespoke-executor.md
@@ -186,12 +186,13 @@ a result.
 [`BespokeExecutor`]: openff.bespokefit.executor.BespokeExecutor
 [`BespokeWorkerConfig`]: openff.bespokefit.executor.BespokeWorkerConfig
 
+(envvars)=
 ## Configuring from the environment
 
 Both the CLI and the Python API can be configured via environment variables.
 
 :::{eval-rst}
-.. autopydantic_settings:: openff.bespokefit.executor.services._settings.Settings
+.. autopydantic_settings:: openff.bespokefit.executor.services.Settings
     :settings-show-json: False
     :settings-show-config-member: False
     :settings-show-config-summary: False
@@ -201,8 +202,12 @@ Both the CLI and the Python API can be configured via environment variables.
     :exclude-members: fragmenter_settings,qc_compute_settings,optimizer_settings,apply_env
     :settings-signature-prefix: Environment Variables
     :field-signature-prefix: env
+    :noindex:
 
-    The following environment variables may be used to configure the Bespoke Executor
+    The following environment variables may be used to configure the Bespoke Executor. Environment variables are typically set in the shell:
 
-:::
+    .. code-block:: shell-session
+
+        $ BEFLOW_KEEP_TMP_FILES=True openff-bespoke executor ...
 
+:::
diff --git a/openff/bespokefit/utilities/_settings.py b/openff/bespokefit/utilities/_settings.py
@@ -65,13 +65,20 @@ class Settings(BaseSettings):
     BEFLOW_OPTIMIZER_KEEP_FILES: bool = False
     """
     .. deprecated:: 0.2.1
-        use BEFLOW_KEEP_TMP_FILES instead
+        use ``BEFLOW_KEEP_TMP_FILES`` instead
 
     Keep the optimizer's temporary files.
     """
 
     BEFLOW_KEEP_TMP_FILES: bool = False
-    """Keep all temporary files."""
+    """
+    Keep all temporary files.
+
+    Temporary files are written to the scratch directory, which can be
+    configured with the ``--directory`` CLI argument. By default, a temporary
+    directory is chosen for scratch, so both this environment variable and that
+    CLI argument must be set to preserve temporary files.
+    """
 
     @property
     def fragmenter_settings(self) -> WorkerSettings: