docs: secureli 540 update documentation (#560)

secureli-540

This ticket was about a problem with configuring the pre-commit library.
I determined that the issue was due to misconfiguration by the user, and
the solution we settled on was to add documentation about how to specify
args in the pre-commit library's configuration file.

Additionally, I updated headings throughout the file. Previously there
were multiple H1s, and the License section was nested underneath the
Configuration section. I've updated it so that there is only a single H1
heading--the title of the document--and the License section is now a
sibling of configuration instead of a child.

## Changes

* Updated headings throughout the file
* Added information and links for the pre-commit library
* Added information about a quirk of how pre-commit handles parameters
that take arguments

## Testing

* All changes are in documentation; no testing required or possible

## Clean Code Checklist
- [ ] Meets acceptance criteria for issue
- [ ] New logic is covered with automated tests
- [ ] Appropriate exception handling added
- [ ] Thoughtful logging included
- [x] Documentation is updated
- [ ] Follow-up work is documented in TODOs
- [ ] TODOs have a ticket associated with them
- [ ] No commented-out code included

README.md

@@ -15,9 +15,9 @@ seCureLI isn’t a magic tool that makes things secure because you have it. It e
 
 Looking to contribute? Read our [CONTRIBUTING.md](https://github.com/slalombuild/secureli/blob/main/CONTRIBUTING.md)
 
-# Installation
+## Installation
 
-## Homebrew
+### Homebrew
 
 To install seCureLI via homebrew, issue the following commands
 
@@ -26,17 +26,17 @@ brew tap slalombuild/secureli
 brew install secureli
 ```
 
-## pip (Package Installer for Python)
+### pip (Package Installer for Python)
 
 To install seCureLI via pip, issue the following commands
 
 ```commandline
 pip install secureli
 ```
 
-# Usage
+## Usage
 
-## Help
+### Help
 
 Once installed you can see the latest documentation for seCureLI by entering the following on a command prompt:
 
@@ -68,7 +68,7 @@ When invoking these commands, you can combine the short versions into a single f
 % secureli init -ry
 ```
 
-## Init
+### Init
 
 After seCureLI is installed, you can use it to configure your local git repository with a set of pre-commit hooks appropriate for your repo, based on the languages found in your repo's source code files.
 
@@ -80,7 +80,7 @@ All you need to do is run:
 
 Running `secureli init` will allow seCureLI to detect the languages in your repo, install pre-commit, install all the appropriate pre-commit hooks for your local repo, run a scan for secrets in your local repo, and update the installed hooks.
 
-## Scan
+### Scan
 
 To manually trigger a scan, run:
 
@@ -90,47 +90,47 @@ To manually trigger a scan, run:
 
 This will run through all hooks and custom scans, unless a `--specific-test` option is used. The default is to scan staged files only. To scan all files instead, use the `--mode all-files` option.
 
-### PII Scan
+#### PII Scan
 
 seCureLI utilizes its own PII scan, rather than using an existing pre-commit hook. To exclude a line from being flagged by the PII scanner, you can use a `disable-pii-scan` marker in a comment to disable the scan for that line.
 
 ```
 test_var = "some dummy data I don't want scanned" # disable-pii-scan
 ```
 
-# Upgrade
+## Upgrade
 
-## Upgrading seCureLI via Homebrew
+### Upgrading seCureLI via Homebrew
 
 If you installed seCureLI using Homebrew, you can use the standard homebrew update command to pull down the latest formula.
 
 ```commandline
 brew update
 ```
 
-## Upgrading via pip
+### Upgrading via pip
 
 If you installed seCureLI using pip, you can use the following command to upgrade to the latest version of seCureLI.
 
 ```commandline
 pip install --upgrade secureli
 ```
 
-## Upgrading pre-commit hooks for repo
+### Upgrading pre-commit hooks for repo
 
 In order to upgrade to the latest released version of each pre-commit hook configured for your repo, use the following command.
 
 ```commandline
 secureli update --latest
 ```
 
-# Configuration
+## Configuration
 
-seCureLI is configurable via a .secureli.yaml file present in the root of your local repository.
+### .secureli.yaml
 
-## .secureli.yaml
+seCureLI is configurable via a `.secureli.yaml` file present in the root of your local repository.
 
-### top level
+#### top level
 
 | Key                | Description                                                                                                        |
 |--------------------|--------------------------------------------------------------------------------------------------------------------|
@@ -140,38 +140,72 @@ seCureLI is configurable via a .secureli.yaml file present in the root of your l
 | `pii_scanner`      | Includes options for seCureLI's PII scanner                                                                        |
 | `telemetry`        | Includes options for seCureLI telemetry/api logging                                                                |
 
-### repo_files
+#### repo_files
 
 | Key                       | Description                                                                                                                                                                                                                                                             |
 | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `max_file_size`           | A number in bytes. Files over this size will not be considered during language analysis, for speed purposes. Default: 100000                                                                                                                                            |
 | `ignored_file_extensions` | Which file extensions not to consider during language analysis.                                                                                                                                                                                                         |
 | `exclude_file_patterns`   | Which file patterns to ignore during language analysis and code analysis execution. Use a typical file pattern you might find in a .gitignore file, such as `*.py` or `tests/`. Certain patterns you will have to wrap in double-quotes for the entry to be valid YAML. |
 
-### echo
+#### echo
 
 | Key     | Description                                                                                                                                        |
 | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `level` | The log level to display to the user. Defaults to ERROR, which includes `error` and `print` messages, without including warnings or info messages. |
 
-### pii_scanner
+#### pii_scanner
 
 | Key                  | Description                                                    |
 |----------------------|----------------------------------------------------------------|
 | `ignored_extensions` | The extensions of files to ignore in addition to the defaults. |
 
-### telemetry
+#### telemetry
 
 | Key       | Description                                                                                                                                                                              |
 | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `api_url` | The url endpoint to post telemetry logs to. This value is an alternative to setting the url as an environment variable. Note: The environment variable will precede this setting value |
 
-## Using Observability Platform to Show Secret Detection Statistics
+### pre-commit
+
+[pre-commit](https://pre-commit.com/) is used for configuring pre-commit hooks. The configuration file is `.secureli/.pre-commit-config.yaml`, relative to the root of your repo. For details on modifying this file, see the pre-commit documentation on [configuring hooks](https://pre-commit.com/#pre-commit-configyaml---hooks).
+
+#### Passing arguments to pre-commit hooks
+
+Special care needs to be taken when passing arguments to pre-commit hooks in `.pre-commit-config.yaml`. In particular, if you're passing parameters which themselves take arguments, you must ensure that both the parameter and its arguments are separate items in the array.
+
+Examples:
+
+**BAD**
+
+```yaml
+- args:
+  - --exclude-files *.md
+```
+
+This is an array with a single element, `["--exclude files *.md"]`. This probably won't work as you're expecting.
+
+**GOOD**
+
+```yaml
+- args:
+  - --exclude-files
+  - *.md
+```
+
+This is an array where the parameter and its argument are separate items; `["--exclude files", "*.md"]`
+
+**ALSO GOOD**
+```yaml
+- args: ["--exclude-files", "*.md"]
+```
+
+### Using Observability Platform to Show Secret Detection Statistics
 
 seCureLI can send secret detection events to an observability platform, such as New Relic. Other platforms may also work, but have not been tested.
 Should you need seCureLI to work with other platforms, please create a new issue in github, or contribute to the open source project.
 
-### Steps for New Relic
+#### Steps for New Relic
 
 - Assuming, seCureLI has been setup and installed, sign up to New Relic Log Platform https://docs.newrelic.com/docs/logs/log-api/introduction-log-api/
 - Retrieve API_KEY and API_ENDPOINT from New Relic. API_ENDPOINT for New Relic should be https://log-api.newrelic.com/log/v1