Merge pull request in-toto#405 from lukpueh/misc-docs-fixes

Misc docs fixes

doc/source/command-line-tools/index.rst

@@ -32,9 +32,3 @@ Utilities
   in-toto-mock: mock in-toto-run <in-toto-mock>
   in-toto-sign: sign/verify individual pieces of metadata <in-toto-sign>
   in-toto-keygen: generate cryptographic keys <in-toto-keygen>
-
-Settings
---------
-.. toctree::
-
-  Settings <settings>

doc/source/configuration.rst

@@ -0,0 +1,8 @@
+Configuration
+=============
+
+.. toctree::
+   :maxdepth: 1
+
+   settings
+   exclude-patterns

doc/source/exclude-patterns.md

@@ -1,4 +1,4 @@
-## Introduction
+## Artifact Exclude Patterns
 
 The optional argument `exclude_patterns` in the `in_toto_run` API, also used by
 `--exclude` in the `in-toto-run` command line tool, applies
@@ -7,7 +7,7 @@ The optional argument `exclude_patterns` in the `in_toto_run` API, also used by
 (materials and products) matched by an exclude pattern are not recorded when
 generating link metadata.
 
-## Pattern Formats
+### Format Specification
 
 - Single asterisks match everything except a slash.
 - Question marks match any one character except a slash.
@@ -41,7 +41,7 @@ generating link metadata.
   particularly necessary for the context of exclude patterns. This can be
   escaped with a back-slash to match a literal exclamation mark (i.e., `\!`).
 
-## Documentation
+### References
 
 - [`pathspec`](http://python-path-specification.readthedocs.io/)
 - [`gitignore`](https://git-scm.com/docs/gitignore)

doc/source/index.rst

@@ -14,6 +14,6 @@ found at `in-toto.io <https://in-toto.io>`_.
    command-line-tools/index
    api
    model
+   configuration
    layout-creation-example
-   exclude-patterns
    Demo Supply Chain <https://github.com/in-toto/demo>

doc/source/command-line-tools/settings.rst → doc/source/settings.rst

@@ -12,6 +12,15 @@ Default values for these settings are defined in the `in_toto.settings
 Settings names are case sensitive and settings values that contain colons are
 parsed as list.
 
+.. note::
+  Settings configured via rcfiles and environment variables are **only**
+  considered if in-toto is invoked form the **command line**, and ignored when
+  using the API.
+  The default ``in_toto.settings``, on the other hand, are considered in both
+  cases, unless overridden via API function arguments or, in the case of CLI
+  usage, environment variables, rcfiles, or CLI arguments.
+
+
 Setting Types
 -------------
 

in_toto/common_args.py

@@ -35,8 +35,8 @@
   "nargs": "+",
   "help": ("path patterns to match paths that should not be recorded as"
            " 'materials' or 'products'. Passed patterns override patterns"
-           " defined in environment variables or config files. (see"
-           " 'ARTIFACT_EXCLUDE_PATTERNS' documentation for additional info)")
+           " defined in environment variables or config files. See Config docs"
+           " for details.")
   }
 
 BASE_PATH_ARGS = ["--base-path"]

in_toto/runlib.py

@@ -467,7 +467,7 @@ def in_toto_run(name, material_list, product_list, link_cmd_args,
         default gpg home directory is used.
 
     exclude_patterns (optional): A list of filename patterns to exclude certain
-        files from being recorded as artifacts.
+        files from being recorded as artifacts. See Config docs for details.
 
     base_path (optional): A path relative to which artifacts are recorded.
         Default is the current working directory.
@@ -634,7 +634,7 @@ def in_toto_record_start(step_name, material_list, signing_key=None,
         default gpg home directory is used.
 
     exclude_patterns (optional): A list of filename patterns to exclude certain
-        files from being recorded as artifacts.
+        files from being recorded as artifacts. See Config docs for details.
 
     base_path (optional): A path relative to which artifacts are recorded.
         Default is the current working directory.