From 281f48a6ff381eced68f297b8d27b12bddbd39a5 Mon Sep 17 00:00:00 2001 From: Lukas Puehringer Date: Wed, 28 Oct 2020 14:25:08 +0100 Subject: [PATCH 1/4] Add 'configuration' docs section Add section for documentation about configuring in-toto tools and detailed information about in-toto command line and function arguments. Move settings.rst and exclude-pattern.md to that docs section. Signed-off-by: Lukas Puehringer --- doc/source/command-line-tools/index.rst | 6 ------ doc/source/configuration.rst | 8 ++++++++ doc/source/index.rst | 2 +- doc/source/{command-line-tools => }/settings.rst | 0 4 files changed, 9 insertions(+), 7 deletions(-) create mode 100644 doc/source/configuration.rst rename doc/source/{command-line-tools => }/settings.rst (100%) diff --git a/doc/source/command-line-tools/index.rst b/doc/source/command-line-tools/index.rst index 47ae971b8..71e87c18f 100644 --- a/doc/source/command-line-tools/index.rst +++ b/doc/source/command-line-tools/index.rst @@ -32,9 +32,3 @@ Utilities in-toto-mock: mock in-toto-run in-toto-sign: sign/verify individual pieces of metadata in-toto-keygen: generate cryptographic keys - -Settings --------- -.. toctree:: - - Settings diff --git a/doc/source/configuration.rst b/doc/source/configuration.rst new file mode 100644 index 000000000..888567ae2 --- /dev/null +++ b/doc/source/configuration.rst @@ -0,0 +1,8 @@ +Configuration +============= + +.. toctree:: + :maxdepth: 1 + + settings + exclude-patterns diff --git a/doc/source/index.rst b/doc/source/index.rst index 57f7dbcca..8cda6bbba 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -14,6 +14,6 @@ found at `in-toto.io `_. command-line-tools/index api model + configuration layout-creation-example - exclude-patterns Demo Supply Chain diff --git a/doc/source/command-line-tools/settings.rst b/doc/source/settings.rst similarity index 100% rename from doc/source/command-line-tools/settings.rst rename to doc/source/settings.rst From 781b3e33a026239a2dac41c88a65664443dfb09e Mon Sep 17 00:00:00 2001 From: Lukas Puehringer Date: Wed, 28 Oct 2020 14:28:02 +0100 Subject: [PATCH 2/4] Clarify scope of rcfile/envvar settings in docs Signed-off-by: Lukas Puehringer --- doc/source/settings.rst | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/doc/source/settings.rst b/doc/source/settings.rst index aae163419..37c630440 100644 --- a/doc/source/settings.rst +++ b/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 ------------- From 224690f0d9faed3dbec54aa8aded239d53465562 Mon Sep 17 00:00:00 2001 From: Lukas Puehringer Date: Wed, 28 Oct 2020 14:30:11 +0100 Subject: [PATCH 3/4] Fix headers + refine titles in exclude pattern doc Bump header levels for consistency and refine header wording. Signed-off-by: Lukas Puehringer --- doc/source/exclude-patterns.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/source/exclude-patterns.md b/doc/source/exclude-patterns.md index fc2d892c5..d5fc45485 100644 --- a/doc/source/exclude-patterns.md +++ b/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) From c86920df39b18f6520cb53538eac7d63569f54e9 Mon Sep 17 00:00:00 2001 From: Lukas Puehringer Date: Wed, 28 Oct 2020 14:33:05 +0100 Subject: [PATCH 4/4] Point to config docs in cli/api argument docs Signed-off-by: Lukas Puehringer --- in_toto/common_args.py | 4 ++-- in_toto/runlib.py | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/in_toto/common_args.py b/in_toto/common_args.py index dfc066e1d..525d109bd 100644 --- a/in_toto/common_args.py +++ b/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"] diff --git a/in_toto/runlib.py b/in_toto/runlib.py index e7335fcd6..2caa54340 100644 --- a/in_toto/runlib.py +++ b/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.