Add P2F docs for using custom templates

[john-odonnell]

Depends on #390

Desired Outcome

From ONYX-14031:

• Overview of how custom templates work and how to reference secrets
• Example custom template
• Description of notable template functions for this use of Golang, with link to external Golang template docs for full details.
• Include note that the initial validation uses fake data to provide early and secure feedback with complete messages, so templates that rely on secret values (i.e. sprintf to format a number) may fail at this stage. But they still would work fine with real secret data.

Implemented Changes

Makes a few additions to PUSH_TO_FILE.md:

• an entry in the Reference Table of Configuration Annotations for conjur.org/secret-file-template.{secret-group}
• section Custom Templates For Secret Files, which includes
  • overview of custom templates
  • detail referencing secrets in custom templates
  • note of template functions in Go's text/template package
  • description of "double-pass" render procedure and a note suggesting against using templates that rely on secret values
  • example custom templates and outputs

Connected Issue/Story

CyberArk internal issue link: ONYX-14031

Definition of Done

At least 1 todo must be completed in the sections below for the PR to be
merged.

Changelog

• The CHANGELOG has been updated, or
• This PR does not include user-facing changes and doesn't require a
  CHANGELOG update

Test coverage

• This PR includes new unit and integration tests to go with the code
  changes, or
• The changes in this PR do not require tests

Documentation

• Docs (e.g. READMEs) were updated in this PR
• A follow-up issue to update official docs has been filed here: insert issue ID
• This PR does not require updating any documentation

Behavior

• This PR changes product behavior and has been reviewed by a PO, or
• These changes are part of a larger initiative that will be reviewed later, or
• No behavior was changed with this PR

Security

• Security architect has reviewed the changes in this PR,
• These changes are part of a larger initiative with a separate security review, or
• There are no security aspects to these changes

[szh]

Looks great! Just need to wait for #390 now

[diverdane]

Nice work on documenting the custom template function!
Just a couple of minor comments, otherwise looks good-to-go.

[diverdane]

I think we need a couple of words before this example secret file output, e.g. "The Secrets Provider will create a secret file with the content:" or something like that.

Same comment applies to other sample custom template output below.

[john-odonnell]

Added this in. For each custom template example, I made sure to include the conjur.org/secret-file-path annotation, because it's required as of now, and I didn't want to spark confusion. Added comments before the output snippets:

Secrets Provider will render the following content for the file /conjur/secrets/<added-file>

[diverdane]

It might help users to have some background context for the .SecretsArray reference here. Maybe something like:

"Here, the .SecretsArray is a reference to Secrets Provider's internal array of secrets that have been retrieved from Conjur. For each entry in this array, there is a secret Alias and a secret Value field that can be referenced in the custom template."

[john-odonnell]

Oh, good idea. Added!

[diverdane]

Approving, but there is one minor typo, otherwise GTG!

[diverdane]

If you have to rebase anyway, there's a typo: tat can be referenced should be that can be referenced.

[john-odonnell]

Rats, my bad. Fixed, rebased, and (officially) opened for review.

[codeclimate]

Code Climate has analyzed commit 6922ede and detected 0 issues on this pull request.

The test coverage on the diff in this pull request is 100.0% (50% is the threshold).

This pull request will bring the total coverage in the repository to 91.4% (0.0% change).

View more on Code Climate.