Merge pull request #60 from norwoodj/new-style-comment-parity

feat: Largely expands all features for old comments to new comments, …

Author: norwoodj

README.md

@@ -53,7 +53,7 @@ GO111MODULE=on go get github.com/norwoodj/helm-docs/cmd/helm-docs
 
 ## Usage
 
-## Pre-commit hook
+### Pre-commit hook
 
 If you want to automatically generate `README.md` files with a pre-commit hook, make sure you
 [install the pre-commit binary](https://pre-commit.com/#install), and add a [.pre-commit-config.yaml file](./.pre-commit-config.yaml)
@@ -66,7 +66,7 @@ pre-commit install-hooks
 
 Future changes to your chart's `requirements.yaml`, `values.yaml`, `Chart.yaml`, or `README.md.gotmpl` files will cause an update to documentation when you commit.
 
-## Running the binary directly
+### Running the binary directly
 
 To run and generate documentation into READMEs for all helm charts within or recursively contained by a directory:
 
@@ -79,7 +79,7 @@ helm-docs --dry-run # prints generated documentation to stdout rather than modif
 The tool searches recursively through subdirectories of the current directory for `Chart.yaml` files and generates documentation
 for every chart that it finds.
 
-## Using docker
+### Using docker
 
 You can mount a directory with charts under `/helm-docs` within the container.
 
@@ -89,7 +89,7 @@ Then run:
 docker run --rm --volume "$(pwd):/helm-docs" -u $(id -u) jnorwood/helm-docs:latest
 ```
 
-# Building from source
+### Building from source
 Notice that you need to have build chain toolkit for given platform and golang installed.
 Next you may need to export some vars to build standalone, non-linked binary for given platform and architecture:
 
@@ -101,26 +101,35 @@ make test
 make
 ```
 
-## Available Templates
-The templates generated by the tool are shown below, and can be included in your `README.md.gotmpl` file like so:
+## Ignoring Chart Directories
+helm-docs supports a `.helmdocsignore` file, exactly like a `.gitignore` file in which one can specify directories to ignore
+when searching for charts. Directories specified need not be charts themselves, so parent directories containing potentially
+many charts can be ignored and none of the charts underneath them will be processed. You may also directly reference the
+Chart.yaml file for a chart to skip processing for it.
+
+
+## Markdown Rendering
+The helm-docs tool uses go-templates to render output documentation. There are a number of sub-templates that are
+referenced in the internal default template and can be used by custom `README.md.gotmpl` templates your repository provides as well.
+
+Templates can be invoked like so:
 ```
 {{ template "template-name" . }}
 ```
 
+And the complete listing of available templates is below:
+
 | Name | Description |
 |------|-------------|
 | chart.header              | The main heading of the generated markdown file |
 | chart.name                | The _name_ field from the chart's `Chart.yaml` file |
 | chart.deprecationWarning  | A deprecation warning which is displayed when the _deprecated_ field from the chart's `Chart.yaml` file is `true` |
 | chart.description         | A description line containing the _description_ field from the chart's `Chart.yaml` file, or "" if that field is not set |
 | chart.version             | The _version_ field from the chart's `Chart.yaml` file |
-| chart.versionLine         | A text line stating the current version of the chart |
 | chart.versionBadge        | A badge stating the current version of the chart |
 | chart.type                | The _type_ field from the chart's `Chart.yaml` file |
-| chart.typeLine            | A text line stating the current type of the chart |
 | chart.typeBadge           | A badge stating the current type of the chart |
 | chart.appVersion          | The _appVersion_ field from the chart's `Chart.yaml` file |
-| chart.appVersionLine      | A text line stating the current appVersion of the chart |
 | chart.appVersionBadge     | A badge stating the current appVersion of the chart |
 | chart.homepage            | The _home_ link from the chart's `Chart.yaml` file, or "" if that field is not set |
 | chart.homepageLine        | A text line stating the current homepage of the chart |
@@ -167,14 +176,7 @@ The tool includes the [sprig templating library](https://github.com/Masterminds/
 in the templates you supply.
 
 
-## Ignoring Chart Directories
-helm-docs supports a `.helmdocsignore` file, exactly like a `.gitignore` file in which one can specify directories to ignore
-when searching for charts. Directories specified need not be charts themselves, so parent directories containing potentially
-many charts can be ignored and none of the charts underneath them will be processed. You may also directly reference the
-Chart.yaml file for a chart to skip processing for it.
-
-
-## values.yaml metadata
+### values.yaml metadata
 This tool can parse descriptions and defaults of values from `values.yaml` files. The defaults are pulled directly from
 the yaml in the file. 
 
@@ -199,21 +201,19 @@ controller:
     # -- Whether to expose the ingress controller to the public world
     enabled: false
 
-  # -- Number of nginx-ingress pods to load balance between. Do not set this below 2.
+  # -- Number of nginx-ingress pods to load balance between.
+  # Do not set this below 2.
   replicas: 2
 ```
 
-There are a number of limitations to this comment format, the foremost being that they can only comprise a single line and while
-the old-style comment for a field could appear anywhere in the file, the new comment must appear **on the line immediately preceding the field being documented.**
-
-Additionally, there are a number of methods for encoding more data in the old comment format, documented later in this guide. These
-extensions are largely not supported with the new _auto-detection_ format.
+New-style comments are much the same as the old-style comments, except that while old comments for a field could appear
+anywhere in the file, new-style comments must appear **on the line(s) immediately preceding the field being documented.**
 
 I invite you to check out the [example-charts](./example-charts) to see how this is done in practice. The `but-auto-comments`
 examples in particular document the new comment format.
 
-Note that comments of the old form can continue on the next line. In that case leave out the double dash, and the lines
-will simply be appended with a space in-between.
+Note that comments can continue on the next line. In that case leave out the double dash, and the lines will simply be
+appended with a space in-between, as in the `controller.replicas` field in the example above
 
 The following rules are used to determine which values will be added to the values table in the README:
 
@@ -283,13 +283,14 @@ inside the chart, you can change the contents of the column like so:
 
 ```yaml
 service:
-  # service.annotations -- Add annotations to the service
+  # -- Add annotations to the service, this is going to be a long comment across multiple lines
+  # but that's fine, these will be concatenated and the @default will be rendered as the default for this field
   # @default -- the chart will add some internal annotations automatically
   annotations: []
 ```
 
-The order is important. The name must be spelled just like the column heading. The first comment must be the
-one specifying the key. The "@default" comment must follow. This is only possible with the old comment format
+The order is important. The first comment line(s) must be the one specifying the key or using the auto-detection feature and
+the description for the field. The `@default` comment must follow.
 
 See [here](./example-charts/custom-template/values.yaml) for an example.
 

example-charts/custom-template/README.md

@@ -2,7 +2,7 @@
 
 Basically the same as the nginx-ingress chart, but using a custom template to include some other content
 
-Current chart version is `0.2.0`
+![Version: 0.2.0](https://img.shields.io/badge/Version-0.2.0-informational?style=flat-square)
 
 ## Additional Information
 

example-charts/custom-template/README.md.gotmpl

@@ -1,7 +1,7 @@
 {{ template "chart.header" . }}
 {{ template "chart.description" . }}
 
-{{ template "chart.versionLine" . }}
+{{ template "chart.versionBadge" . }}{{ template "chart.typeBadge" . }}{{ template "chart.appVersionBadge" . }}
 
 ## Additional Information
 

example-charts/custom-template/values.yaml

@@ -4,33 +4,33 @@ controller:
     repository: nginx-ingress-controller
     tag: "18.0831"
 
-  # controller.persistentVolumeClaims -- List of persistent volume claims to create.
+  # -- List of persistent volume claims to create.
   # For very long comments, break them into multiple lines.
   # @default -- the chart will construct this list internally unless specified
   persistentVolumeClaims: []
 
   extraVolumes:
     - name: config-volume
       configMap:
-        # controller.extraVolumes[0].configMap.name -- Uses the name of the configmap created by this chart
+        # -- Uses the name of the configmap created by this chart
         name: nginx-ingress-config
 
-  # controller.ingressClass -- Name of the ingress class to route through this controller
+  # -- Name of the ingress class to route through this controller
   ingressClass: nginx
 
-  # controller.podLabels -- The labels to be applied to instances of the controller pod
+  # -- The labels to be applied to instances of the controller pod
   podLabels: {}
 
   publishService:
-    # controller.publishService.enabled -- Whether to expose the ingress controller to the public world
+    # -- Whether to expose the ingress controller to the public world
     enabled: false
 
-  # controller.replicas -- (int) Number of nginx-ingress pods to load balance between
+  # -- (int) Number of nginx-ingress pods to load balance between
   replicas:
 
   service:
     annotations:
-      # controller.service.annotations."external-dns.alpha.kubernetes.io/hostname" -- Hostname to be assigned to the ELB for the service
+      # -- Hostname to be assigned to the ELB for the service
       external-dns.alpha.kubernetes.io/hostname: stupidchess.jmn23.com
 
     type: LoadBalancer

example-charts/full-template/README.md

@@ -16,10 +16,6 @@ A chart for showing every README-element
 
 1.0.0
 
-## `chart.versionLine`
-
-Current chart version is `1.0.0`
-
 ## `chart.versionBadge`
 
 ![Version: 1.0.0](https://img.shields.io/badge/Version-1.0.0-informational?style=flat-square)
@@ -28,10 +24,6 @@ Current chart version is `1.0.0`
 
 application
 
-## `chart.typeLine`
-
-Current chart type is `application`
-
 ## `chart.typeBadge`
 
 ![Type: application](https://img.shields.io/badge/Type-application-informational?style=flat-square)
@@ -40,10 +32,6 @@ Current chart type is `application`
 
 13.0.0
 
-## `chart.appVersionLine`
-
-Current chart appVersion is `13.0.0`
-
 ## `chart.appVersionBadge`
 
 ![AppVersion: 13.0.0](https://img.shields.io/badge/AppVersion-13.0.0-informational?style=flat-square)

example-charts/full-template/README.md.gotmpl

@@ -22,10 +22,6 @@
 
 {{ template "chart.version" . }}
 
-## `chart.versionLine`
-
-{{ template "chart.versionLine" . }}
-
 ## `chart.versionBadge`
 
 {{ template "chart.versionBadge" . }}
@@ -34,9 +30,6 @@
 
 {{ template "chart.type" . }}
 
-## `chart.typeLine`
-
-{{ template "chart.typeLine" . }}
 
 ## `chart.typeBadge`
 
@@ -46,10 +39,6 @@
 
 {{ template "chart.appVersion" . }}
 
-## `chart.appVersionLine`
-
-{{ template "chart.appVersionLine" . }}
-
 ## `chart.appVersionBadge`
 
 {{ template "chart.appVersionBadge" . }}

example-charts/most-empty/README.md

@@ -1,6 +1,6 @@
 # most-empty
 
-Current chart version is `0.2.0`
+![Version: 0.2.0](https://img.shields.io/badge/Version-0.2.0-informational?style=flat-square)
 
 This is a good example of all the fields that don't appear when they aren't set in chart metadata. `description`,
 `requirements`, and `values` are all empty and don't appear here.

example-charts/most-empty/README.md.gotmpl

@@ -1,7 +1,7 @@
 {{ template "chart.header" . }}
 {{ template "chart.description" . }}
 
-{{ template "chart.versionLine" . }}
+{{ template "chart.versionBadge" .  }}{{ template "chart.typeBadge" .  }}{{ template "chart.appVersionBadge" .  }}
 
 This is a good example of all the fields that don't appear when they aren't set in chart metadata. `description`,
 `requirements`, and `values` are all empty and don't appear here.

example-charts/nginx-ingress-but-auto-comments/README.md

@@ -34,8 +34,8 @@ A simple wrapper around the stable/nginx-ingress chart that adds a few of our co
 | controller.livenessProbe.httpGet.path | string | `"/healthz"` | This is the liveness check endpoint |
 | controller.name | string | `"controller"` |  |
 | controller.persistentVolumeClaims | list | `[]` | List of persistent volume claims to create |
-| controller.podLabels | object | `{}` | The labels to be applied to instances of the controller pod |
+| controller.podLabels | object | A number of chart-specific labels | The labels to be applied to instances of the controller pod. By default, a number of labels will automatically be applied |
 | controller.publishService.enabled | bool | `false` | Whether to expose the ingress controller to the public world |
-| controller.replicas | int | `nil` | Number of nginx-ingress pods to load balance between |
+| controller.replicas | int | `nil` | Number of nginx-ingress pods to load balance between. Do not set this below 2 |
 | controller.service.annotations."external-dns.alpha.kubernetes.io/hostname" | string | `"stupidchess.jmn23.com"` | Hostname to be assigned to the ELB for the service |
 | controller.service.type | string | `"LoadBalancer"` |  |

example-charts/nginx-ingress-but-auto-comments/values.yaml

@@ -23,14 +23,17 @@ controller:
   # -- Name of the ingress class to route through this controller
   ingressClass: nginx
 
-  # -- The labels to be applied to instances of the controller pod
+  # -- The labels to be applied to instances of the controller pod.
+  # By default, a number of labels will automatically be applied
+  # @default -- A number of chart-specific labels
   podLabels: {}
 
   publishService:
     # -- Whether to expose the ingress controller to the public world
     enabled: false
 
-  # -- (int) Number of nginx-ingress pods to load balance between
+  # -- (int) Number of nginx-ingress pods to load balance between.
+  # Do not set this below 2
   replicas:
 
   service:

example-charts/special-characters-but-auto-comments/values.yaml

@@ -18,4 +18,5 @@ htmlSnippets:
   two: ""
 
   # -- Another description
-  three: "<html><head></head></html>"
+  # @default -- `"<html><head></head></html>"`
+  three: ""

pkg/document/model.go

@@ -11,6 +11,7 @@ import (
 type valueRow struct {
 	Key             string
 	Type            string
+	AutoDefault     string
 	Default         string
 	AutoDescription string
 	Description     string

pkg/document/template.go

@@ -61,9 +61,6 @@ func getDeprecatedTemplate() string {
 func getVersionTemplates() string {
 	versionBuilder := strings.Builder{}
 	versionBuilder.WriteString(`{{ define "chart.version" }}{{ .Version }}{{ end }}\n`)
-	versionBuilder.WriteString(`{{ define "chart.versionLine" }}`)
-	versionBuilder.WriteString("{{ if .Version }}Current chart version is `{{ .Version }}`{{ end }}")
-	versionBuilder.WriteString("{{ end }}")
 	versionBuilder.WriteString(`{{ define "chart.versionBadge" }}`)
 	versionBuilder.WriteString("![Version: {{ .Version }}](https://img.shields.io/badge/Version-{{ .Version }}-informational?style=flat-square) ")
 	versionBuilder.WriteString("{{ end }}")
@@ -74,9 +71,6 @@ func getVersionTemplates() string {
 func getTypeTemplate() string {
 	typeBuilder := strings.Builder{}
 	typeBuilder.WriteString(`{{ define "chart.type" }}{{ .Type }}{{ end }}\n`)
-	typeBuilder.WriteString(`{{ define "chart.typeLine" }}`)
-	typeBuilder.WriteString("{{ if .Type }}Current chart type is `{{ .Type }}`{{ end }}")
-	typeBuilder.WriteString("{{ end }}")
 	typeBuilder.WriteString(`{{ define "chart.typeBadge" }}`)
 	typeBuilder.WriteString("{{ if .Type }}![Type: {{ .Type }}](https://img.shields.io/badge/Type-{{ .Type }}-informational?style=flat-square) {{ end }}")
 	typeBuilder.WriteString("{{ end }}")
@@ -87,9 +81,6 @@ func getTypeTemplate() string {
 func getAppVersionTemplate() string {
 	appVersionBuilder := strings.Builder{}
 	appVersionBuilder.WriteString(`{{ define "chart.appVersion" }}{{ .AppVersion }}{{ end }}\n`)
-	appVersionBuilder.WriteString(`{{ define "chart.appVersionLine" }}`)
-	appVersionBuilder.WriteString("{{ if .AppVersion }}Current chart appVersion is `{{ .AppVersion }}`{{ end }}")
-	appVersionBuilder.WriteString("{{ end }}")
 	appVersionBuilder.WriteString(`{{ define "chart.appVersionBadge" }}`)
 	appVersionBuilder.WriteString("{{ if .AppVersion }}![AppVersion: {{ .AppVersion }}](https://img.shields.io/badge/AppVersion-{{ .AppVersion }}-informational?style=flat-square) {{ end }}")
 	appVersionBuilder.WriteString("{{ end }}")
@@ -202,7 +193,7 @@ func getValuesTableTemplates() string {
 	valuesSectionBuilder.WriteString("| Key | Type | Default | Description |\n")
 	valuesSectionBuilder.WriteString("|-----|------|---------|-------------|\n")
 	valuesSectionBuilder.WriteString("  {{- range .Values }}")
-	valuesSectionBuilder.WriteString("\n| {{ .Key }} | {{ .Type }} | {{ .Default }} | {{ if .Description }}{{ .Description }}{{ else }}{{ .AutoDescription }}{{ end }} |")
+	valuesSectionBuilder.WriteString("\n| {{ .Key }} | {{ .Type }} | {{ if .Default }}{{ .Default }}{{ else }}{{ .AutoDefault }}{{ end }} | {{ if .Description }}{{ .Description }}{{ else }}{{ .AutoDescription }}{{ end }} |")
 	valuesSectionBuilder.WriteString("  {{- end }}")
 	valuesSectionBuilder.WriteString("{{ end }}")