Custom Template Support

.gitignore

@@ -2,3 +2,4 @@
 /envdoc
 coverage.out
 test.cover
+.idea

README.md

@@ -73,6 +73,8 @@ type Config struct {
  * `-target` (`enum(caarlos0, cleanenv)` string, optional, default `caarlos0`) - Set env library target.
  * `-output` (path string, **required**) - Output file name for generated documentation.
  * `-format` (`enum(markdown, plaintext, html, dotenv, json)` string, *optional*) - Output format for documentation.  Default is `markdown`.
+ * `-template` (path string, *optional*) - Path to a custom template file for rendering the output. It has priority over `-format`.
+ * `-title` (string, *optional*, default `Environment Variables`) - Title to be used as the header of the generated file.
  * `-no-styles` (`bool`, *optional*) - If true, CSS styles will not be included for `html` format.
  * `-env-prefix` (`string`, *optional*) - Sets additional global prefix for all environment variables.
  * `-tag-name` (string, *optional*, default: `env`) - Use custom tag name instead of `env`.
@@ -126,6 +128,70 @@ This tool is compatible with
 
 *Let me know about any new lib to check compatibility.*
 
+## Custom Templates
+envdoc also supports user-defined templates for more specific layouts provided with the `-template` flag.
+
+Examples can be found [here](_examples/custom-templates).
+
+### Template Data
+Custom templates are expected to be [Go text templates](https://pkg.go.dev/text/template) and are executed with the following data.
+
+#### Top-Level Data
+| Field      | Type              | Description                                                                                             |                                           
+|------------|-------------------|---------------------------------------------------------------------------------------------------------|
+| `Title`    | `string`          | Value of the `-title` flag. Defaults to `Environment Variables`. Useful as a file header.               |
+| `Sections` | `[]renderSection` | A list of structs matched by the `-target` flag.                                                        |
+| `Style`    | `bool`            | The opposite of the the `-no-style` flag (hence it defaults to `true`). Useful for toggling CSS styles. |
+
+#### Section: renderSection
+Each section represents a struct holding fields that map to environment variables.
+
+| Field    | Type            | Description                                                       |
+|----------|-----------------|-------------------------------------------------------------------|
+| `Name`   | `string`        | Name of the struct.                                               |
+| `Doc`    | `string`        | Description of the struct (parsed from the struct's doc comment). |
+| `Items`  | `[]renderItem`  | List of fields within the struct.                                 |
+
+#### Item: renderItem
+Each item represents a struct field that maps to an environment variable.
+
+| Field          | Type            | Description                                                                                 |
+|----------------|-----------------|---------------------------------------------------------------------------------------------|
+| `EnvName`      | `string`        | Name of the environment variable.                                                           |
+| `Doc`          | `string`        | Description of the variable (parsed from the field's doc comment).                          |
+| `EnvDefault`   | `string`        | Optional default value.                                                                     |
+| `EnvSeparator` | `string`        | Character used to separate items in slices and maps.                                        |
+| `Required`     | `bool`          | Signifies if the variable must be set.                                                      |
+| `NonEmpty`     | `bool`          | Signifies if the variable must not be empty if set. Applies only to `caarlos0`              |
+| `Expand`       | `bool`          | Signifies if the value is expandable from environment variables. Applies only to `caarlos0` |
+| `FromFile`     | `bool`          | Signifies if the value is read from a file. Applies only to `caarlos0`                      |
+| `Children`     | `[]renderItem`  | Nested structs in item. Applies only to `cleanenv`.                                         |
+
+### Functions
+Custom templates support the following string functions from the standard library:
+- `repeat`
+- `split`
+- `join`
+- `contains`
+- `toLower`
+- `toUpper`
+- `toTitle`
+- `replace`
+- `hasPrefix`
+- `hasSuffix`
+- `trimSpace`
+- `trimPrefix`
+- `trimSuffix`
+- `trimLeft`
+- `trimRight`
+
+In addition to the standard functions above, the following are supported:
+- `strAppend`: `func (arr []string, item string) []string` - Appends `item` to `arr`.
+- `strSlice`: `func () []string` - Makes a new empty slice. 
+- `list`: `func(args ...any) []any` - Returns the variadic args as a slice.
+- `sum`: `func(args ...int) int` - Returns the sum of the variadic args.
+- `marshalIndent`: `func(v any) (string, error)` - Marshals the given value into a JSON string. <br>
+  Returns an error if the value is not a valid JSON.
 
 ## Contributing
 

_examples/custom-templates/config.go

@@ -0,0 +1,46 @@
+package main
+
+// Config is an example configuration structure.
+// It is used to generate documentation from custom templates.
+//
+//go:generate go run ../../ -output doc_table.md -template mdtable.tmpl -types * -title Configuration
+//go:generate go run ../../ -output doc_tree.txt -target cleanenv -template texttree.tmpl -types * -title Configuration
+//go:generate go run ../../ -output doc_table_styled.html -template htmltable.tmpl -types *
+//go:generate go run ../../ -output doc_table_plain.html -template htmltable.tmpl -types * -no-styles true
+type Config struct {
+	// Secret is a secret value that is read from a file.
+	Secret string `env:"SECRET,file"`
+	// Password is a password that is read from a file.
+	Password string `env:"PASSWORD,file" envDefault:"/tmp/password" env-default:"/tmp/password" json:"password"`
+	// Certificate is a certificate that is read from a file.
+	Certificate string `env:"CERTIFICATE,file,expand" envDefault:"${CERTIFICATE_FILE}" env-default:"${CERTIFICATE_FILE}"`
+	// Key is a secret key.
+	SecretKey string `env:"SECRET_KEY,required" env-required:"true" json:"secret_key"`
+	// SecretVal is a secret value.
+	SecretVal string `json:"secret_val" env:"SECRET_VAL,notEmpty"`
+
+	// Hosts is a list of hosts.
+	Hosts []string `env:"HOSTS,required" env-required:"true" envSeparator:":" env-separator:":"`
+
+	// Words is just a list of words.
+	Words []string `env:"WORDS,file" envDefault:"one,two,three" env-default:"one,two,three"`
+
+	Comment string `env:"COMMENT,required" env-required:"true" envDefault:"This is a comment." env-default:"This is a comment."` // Just a comment.
+
+	// AllowMethods is a list of allowed methods.
+	AllowMethods string `env:"ALLOW_METHODS" envDefault:"GET, POST, PUT, PATCH, DELETE, OPTIONS" env-default:"GET, POST, PUT, PATCH, DELETE, OPTIONS"`
+
+	// Anon is an anonymous structure.
+	Anon struct {
+		// User is a user name.
+		User string `env:"USER,required" env-required:"true"`
+		// Pass is a password.
+		Pass string `env:"PASS,required" env-required:"true"`
+	} `envPrefix:"ANON_"`
+}
+
+// NextConfig is a configuration structure to generate multiple doc sections.
+type NextConfig struct {
+	// Mount is a mount point.
+	Mount string `env:"MOUNT,required" env-required:"true"`
+}

_examples/custom-templates/doc_table.md

@@ -0,0 +1,28 @@
+# Configuration
+
+## Config
+
+Config is an example configuration structure.
+It is used to generate documentation from custom templates.
+
+| Name | Description | Default | Attributes |
+|------|-------------|---------|------------|
+| `SECRET` | Secret is a secret value that is read from a file. |  | `From File` |
+| `PASSWORD` | Password is a password that is read from a file. | `/tmp/password` | `From File` |
+| `CERTIFICATE` | Certificate is a certificate that is read from a file. | `${CERTIFICATE_FILE}` | `Expandable`, `From File` |
+| `SECRET_KEY` | Key is a secret key. |  | `REQUIRED` |
+| `SECRET_VAL` | SecretVal is a secret value. |  | `REQUIRED`, `Not Empty` |
+| `HOSTS` | Hosts is a list of hosts. |  | `REQUIRED`, `Separated by :` |
+| `WORDS` | Words is just a list of words. | `one,two,three` | `From File`, `Separated by ,` |
+| `COMMENT` | Just a comment. | `This is a comment.` | `REQUIRED` |
+| `ALLOW_METHODS` | AllowMethods is a list of allowed methods. | `GET, POST, PUT, PATCH, DELETE, OPTIONS` |  |
+| `ANON_USER` | User is a user name. |  | `REQUIRED` |
+| `ANON_PASS` | Pass is a password. |  | `REQUIRED` |
+
+## NextConfig
+
+NextConfig is a configuration structure to generate multiple doc sections.
+
+| Name | Description | Default | Attributes |
+|------|-------------|---------|------------|
+| `MOUNT` | Mount is a mount point. |  | `REQUIRED` |

_examples/custom-templates/doc_table_plain.html

@@ -0,0 +1,124 @@
+<h1>Environment Variables</h1>
+
+        <h2>Config</h2>
+
+        <p>Config is an example configuration structure.
+It is used to generate documentation from custom templates.</p>
+
+
+    <table>
+        <thead>
+        <tr>
+            <th>Name</th>
+            <th>Description</th>
+            <th>Default</th>
+            <th>Attributes</th>
+        </tr>
+        </thead>
+        <tbody>
+
+            <tr>
+                <td><code>SECRET</code></td>
+                <td>Secret is a secret value that is read from a file.</td>
+                <td></td>
+                <td><code>From File</code></td>
+            </tr>
+
+            <tr>
+                <td><code>PASSWORD</code></td>
+                <td>Password is a password that is read from a file.</td>
+                <td><code>/tmp/password</code></td>
+                <td><code>From File</code></td>
+            </tr>
+
+            <tr>
+                <td><code>CERTIFICATE</code></td>
+                <td>Certificate is a certificate that is read from a file.</td>
+                <td><code>${CERTIFICATE_FILE}</code></td>
+                <td><code>Expandable</code>, <code>From File</code></td>
+            </tr>
+
+            <tr>
+                <td><code>SECRET_KEY</code></td>
+                <td>Key is a secret key.</td>
+                <td></td>
+                <td><code>REQUIRED</code></td>
+            </tr>
+
+            <tr>
+                <td><code>SECRET_VAL</code></td>
+                <td>SecretVal is a secret value.</td>
+                <td></td>
+                <td><code>REQUIRED</code>, <code>Not Empty</code></td>
+            </tr>
+
+            <tr>
+                <td><code>HOSTS</code></td>
+                <td>Hosts is a list of hosts.</td>
+                <td></td>
+                <td><code>REQUIRED</code>, <code>Separated by :</code></td>
+            </tr>
+
+            <tr>
+                <td><code>WORDS</code></td>
+                <td>Words is just a list of words.</td>
+                <td><code>one,two,three</code></td>
+                <td><code>From File</code>, <code>Separated by ,</code></td>
+            </tr>
+
+            <tr>
+                <td><code>COMMENT</code></td>
+                <td>Just a comment.</td>
+                <td><code>This is a comment.</code></td>
+                <td><code>REQUIRED</code></td>
+            </tr>
+
+            <tr>
+                <td><code>ALLOW_METHODS</code></td>
+                <td>AllowMethods is a list of allowed methods.</td>
+                <td><code>GET, POST, PUT, PATCH, DELETE, OPTIONS</code></td>
+                <td></td>
+            </tr>
+
+            <tr>
+                <td><code>ANON_USER</code></td>
+                <td>User is a user name.</td>
+                <td></td>
+                <td><code>REQUIRED</code></td>
+            </tr>
+
+            <tr>
+                <td><code>ANON_PASS</code></td>
+                <td>Pass is a password.</td>
+                <td></td>
+                <td><code>REQUIRED</code></td>
+            </tr>
+        </tbody>
+    </table>
+
+        <h2>NextConfig</h2>
+
+        <p>NextConfig is a configuration structure to generate multiple doc sections.</p>
+
+
+    <table>
+        <thead>
+        <tr>
+            <th>Name</th>
+            <th>Description</th>
+            <th>Default</th>
+            <th>Attributes</th>
+        </tr>
+        </thead>
+        <tbody>
+
+            <tr>
+                <td><code>MOUNT</code></td>
+                <td>Mount is a mount point.</td>
+                <td></td>
+                <td><code>REQUIRED</code></td>
+            </tr>
+        </tbody>
+    </table>
+
+