Package: doxy-helm
doxy-helmThe doxy-helm tool auto-generates documentation from helm charts into markdown files. The resulting files contain metadata about their respective chart and a table with each of the chart's values, their defaults, and an optional description parsed from comments.The markdown generation is entirelygotemplate(Currently) driven. The tool parses metadata from charts and generates a number of sub-templates that can be referenced in a template file (by defaultREADME.md.gotmpl).
If no template file is provided, the tool has a default internal template that will generate a reasonably formatted README.FeaturesDocumentation Generation:Automatically generates documentation from Helm charts into markdown files.Metadata Inclusion:Provides comprehensive metadata about charts and their corresponding values.Comment Parsing:Parses descriptions and default values from comments in Helm charts.Template-Driven:Utilizesgotemplatefor markdown generation (Currently).Custom CSS:Allows the addition of custom CSS for each element in tables, including entire tables or specific rows.Global CSS:Enables the application of global CSS to all elements in all tables.Table Manipulation:Transfers and reorders tables to sections of your choice.Chart Directory Exclusion:Supports the use of.helmdocsignorefiles to ignore specific chart directories.Subdirectory Search:Facilitates the auto-search for charts in subdirectories using the--chart-search-rootflag.Table Ordering:Provides table ordering options by key, type, default, or description using the--order-byflag.Future FeaturesIgnoring Elements:Introduces the capability to ignore elements or entire tables using the@ignoretag.File Inclusion:Enables loading different files inside the Go template for more flexibility.Direct Go Template Rendering:Allows rendering of direct Go templates for advanced customization.Column Navigation:Links each column name to the corresponding data line in the source file.Default Values:You dont have to provide defult value every time ou can add comment that represent the default value by@default.The most useful aspect of this tool is the auto-detection of field descriptions from comments:# -- Image to use for deploying, must support an entrypoint which creates users/databases from appropriate config filesstatefulset:image:# -- Imeeeeeage to use for deploying, must support an entrypoint which creates users/databases from appropriate config files# -- [section=global] Image to use for depeeloying, must support an entrypoint which creates users/databases from appropriate config filesrepository:jnorwood/postgresqtag:"11"# -- Additional volumes to be mounted into the database containerextraVolumes:# this is commeooooooooooooontc-name:dataemptyDir:{}emptyDisr:{}# this is commentemptyDisqr:{}# -- Configure the healthcheck for the databaselivenessProbe:enabled:false# -- The labels to be applied to instances of the databasepodLabels:{}Resulting in a resulting README section like so:> globalstatefulsetImage to use for deploying, must support an entrypoint which creates users/databases from appropriate config filesKeyTypeDefaultDescriptionstatefulsetdict`{'image': {'repository': 'jnorwood/postgresq', 'tag': '11'}, 'extraVolumes': [{'name': 'data', 'emptyDir': {}, 'emptyDisr': {}, 'emptyDisqr': {}}], 'livenessProbe': {'enabled': False}, 'podLabels': {}}`Image to use for deploying, must support an entrypoint which creates users/databases from appropriate config filesstatefulset.imagedict`{'repository': 'jnorwood/postgresq', 'tag': '11'}`statefulset.image.repositorystr`jnorwood/postgresq`Imeeeeeage to use for deploying, must support an entrypoint which creates users/databases from appropriate config filesstatefulset.image.tagstr`11`statefulset.extraVolumeslist`[{'name': 'data', 'emptyDir': {}, 'emptyDisr': {}, 'emptyDisqr': {}}]`Additional volumes to be mounted into the database containerstatefulset.extraVolumes[0]dict`{'name': 'data', 'emptyDir': {}, 'emptyDisr': {}, 'emptyDisqr': {}}`statefulset.livenessProbedict`{'enabled': False}`Configure the healthcheck for the databasestatefulset.livenessProbe.enabledbool`False`statefulset.podLabelsdict`{}`The labels to be applied to instances of the databaseYou may observe that certain intricate fields (lists and dictionaries) are documented, while others are not. Additionally, simple fields such as statefulset.image.tag are documented even in the absence of a description comment. The criteria determining what gets documented in the final table and what does not will be elaborated on later in this document.Installationdoxy-helm can be installed usingpip:pipinstalldoxy-helmTo build from source in this repository:gitclonehttps://github.com/tactful-ai/doxy-helmcddoxy-helm
pythonsetup.pysdistbdist_wheel
pipinstall.UsageUsing Dockerdockerrun--rm-v./Helm-files-location:/appwaer/doxy-helm:latestRunning the binary directlyTo run and generate documentation into READMEs for all helm charts within or recursively contained by a directory:doxy# ORdoxy--dry-run# prints generated documentation to stdout rather than modifying READMEsThe tool searches recursively through subdirectories of the current directory forChart.yamlfiles and generates documentation for every chart that it finds.Ignoring Chart DirectoriesThe doxy-helm tool supports a .helmdocsignore file, similar to a .gitignore file, where you can specify directories to be excluded from the chart search process. This feature allows you to ignore directories that might contain multiple charts or unrelated files, ensuring that only the desired charts are processed. You can also directly reference the Chart.yaml file for a specific chart to prevent it from being processed.By using the .helmdocsignore file, you have the flexibility to tailor the chart search process to your project's structure and requirements. This is particularly useful when you want to focus on specific charts and exclude others that are not relevant for documentation generation.Markdown RenderingWhen utilizing the doxy-helm tool, it's crucial to be mindful of two essential parameters. The first parameter, --chart-search-root, designates the root directory from which the tool will conduct a recursive search for charts to generate documentation for. The second parameter, --template-files, specifies a list of gotemplate files that should be employed in crafting the resulting markdown file for each discovered chart. By default, the values for these parameters are --chart-search-root=. and --template-files=README.md.gotmpl.Should you provide a template file using just its filename, this indicates that the file should be interpreted as being relative to each individual chart directory found. Conversely, if a template file is provided as a relative path, such as in the form of --template-files=./_templates.gotmpl --template-files=README.md.gotmpl, then it is interpreted as being relative to the chart-search-root. This level of flexibility enables you to adapt the template usage according to the specific location and structure of your chart directories.This repo is a good example of this in action. If you take a look at the.pre-commit-config.yaml filehere, you'll see our search root is set toexample-chartsand the list of templates used for each chart is the_templates.gotmpl file in that directoryand the README.md.gotmpl file in each chart directory.If any of the specified template files is not found for a chart (you'll notice most of the example charts do not have a README.md.gotmpl)
file, then the internal default template is used instead.In addition to extra defined templates you specify in these template files, there are quite a few built-in templates that
can be used as well:NameDescriptionchart.headerThe main heading of the generated markdown filechart.nameThenamefield from the chart'sChart.yamlfilechart.deprecationWarningA deprecation warning which is displayed when thedeprecatedfield from the chart'sChart.yamlfile istruechart.descriptionA description line containing thedescriptionfield from the chart'sChart.yamlfile, or "" if that field is not setchart.versionTheversionfield from the chart'sChart.yamlfilechart.versionBadgeA badge stating the current version of the chartchart.typeThetypefield from the chart'sChart.yamlfilechart.typeBadgeA badge stating the current type of the chartchart.appVersionTheappVersionfield from the chart'sChart.yamlfilechart.appVersionBadgeA badge stating the current appVersion of the chartchart.homepageThehomelink from the chart'sChart.yamlfile, or "" if that field is not setchart.homepageLineA text line stating the current homepage of the chartchart.maintainersHeaderThe heading for the chart maintainers sectionchart.maintainersTableA table of the chart's maintainerschart.maintainersSectionA section headed by the maintainersHeader from above containing the maintainersTable from above or "" if there are no maintainerschart.sourcesHeaderThe heading for the chart sources sectionchart.sourcesListA list of the chart's sourceschart.sourcesSectionA section headed by the sourcesHeader from above containing the sourcesList from above or "" if there are no sourceschart.kubeVersionThekubeVersionfield from the chart'sChart.yamlfilechart.kubeVersionLineA text line stating the required Kubernetes version for the chartchart.requirementsHeaderThe heading for the chart requirements sectionchart.requirementsTableA table of the chart's required sub-chartschart.requirementsSectionA section headed by the requirementsHeader from above containing the kubeVersionLine and/or the requirementsTable from above or "" if there are no requirementschart.valuesHeaderThe heading for the chart values sectionchart.valuesTableA table of the chart's values parsed from thevalues.yamlfile (see below)chart.valuesSectionA section headed by the valuesHeader from above containing the valuesTable from above or "" if there are no valuesThe default internal template mentioned above uses many of these and looks like this:{{ template "chart.header" . }}
{{ template "chart.deprecationWarning" . }}

{{ template "chart.badgesSection" . }}

{{ template "chart.description" . }}

{{ template "chart.homepageLine" . }}

{{ template "chart.maintainersSection" . }}

{{ template "chart.sourcesSection" . }}

{{ template "chart.requirementsSection" . }}

{{ template "chart.valuesSection" . }}The tool also includes the internal comment parser, so those functions can be used in the templates you supply.values.yaml metadataThis tool can parse descriptions and defaults of values fromvalues.yamlfiles. The defaults are pulled directly from
the yaml in the file.controller:publishService:# -- Whether to expose the ingress controller to the public worldenabled:false# -- Number of nginx-ingress pods to load balance between.# Do not set this below 2.replicas:2I invite you to check out theexample-chartsto see how this is done in practice. Thebut-auto-commentsexamples in particular document the new comment format.Note that comments is only for the line that start with # -- . In that case leave out the double dash, and the lines will simply be appended with a space in-between, as in thecontroller.replicasfield in the example aboveThe following rules are used to determine which values will be added to the values table in the README:By default, onlyleaf nodes, that is, fields of typeint,string,float,bool, empty lists, and empty maps
are added as rows in the values table. These fields will be added even if they do not have a description commentLists and maps which contain elements will be added as rows in the values table.
comment which refers to theme.g. In this case, bothlivenessProbeandlivenessProbe.httpGet.pathwill be added as rows in
the values table, alsolivenessProbe.httpGet.portwill be added# -- Configure the healthcheck for the ingress controllerlivenessProbe:httpGet:# -- This is the liveness check endpointpath:/healthzport:httpResults in:livenessProbeKeyTypeDefaultDescriptionlivenessProbedict`{'httpGet': {'path': '/healthz', 'port': 'http'}}`Configure the healthcheck for the ingress controllerlivenessProbe.httpGetdict`{'path': '/healthz', 'port': 'http'}`livenessProbe.httpGet.pathstr`/healthz`This is the liveness check endpointlivenessProbe.httpGet.portstr`http`Custom cssyou can add css for one table or element in table or even for add tables in the values section by adding@customcsstag to the start of table.
and for each single css that can be added to the table or element in table or even for add tables in the values section by adding-- {the css you want}tag to the start of table.# -- @custom_css {color: red;}# -- hello# -- {text-align: right;}controller:name:controller# -- {color: purple;}image:repository:nginx-ingress-controllertag:"18.0831"and the result aable will be look like that:controllerhelloKeyTypeDefaultDescriptioncontrollerdict`{'name': 'controller', 'image': {'repository': 'nginx-ingress-controller', 'tag': '18.0831'}, 'persistentVolumeClaims': [], 'extraVolumes': [{'name': 'config-volume', 'configMap': {'name': 'nginx-ingress-config'}}], 'ingressClass': 'nginx'}`hellocontroller.namestr`controller`controller.imagedict`{'repository': 'nginx-ingress-controller', 'tag': '18.0831'}`controller.image.repositorystr`nginx-ingress-controller`controller.image.tagstr`18.0831`organize and reorder the tableYou can easily divide your tables into logical sections and reorder them by adding a[]tag at the start of the table's comment. This action will relocate the table to the desired section and allow you to reorder it according to your preference. This approach enables you to effectively organize and structure the tables within the values section, aligning with your desired logical order.
You should take care of transfering table since it executes in order of less.that mean big section will be transfered before the small one.# -- [section-main]statefulset:image:# -- Imeeeeeage to use for deploying, must support an entrypoint which creates users/databases from appropriate config filesrepository:jnorwood/postgresqtag:"11"it will be rendered as follow:> section-mainstatefulsetImage to use for deploying, must support an entrypoint which creates users/databases from appropriate config filesKeyTypeDefaultDescriptionstatefulsetdict`{'image': {'repository': 'jnorwood/postgresq', 'tag': '11'}, 'extraVolumes': [{'name': 'data', 'emptyDir': {}, 'emptyDisr': {}, 'emptyDisqr': {}}], 'livenessProbe': {'enabled': False}, 'podLabels': {}}`Image to use for deploying, must support an entrypoint which creates users/databases from appropriate config filesstatefulset.imagedict`{'repository': 'jnorwood/postgresq', 'tag': '11'}`statefulset.image.repositorystr`jnorwood/postgresq`Imeeeeeage to use for deploying, must support an entrypoint which creates users/databases from appropriate config filesstatefulset.image.tagstr`11`statefulset.extraVolumeslist`[{'name': 'data', 'emptyDir': {}, 'emptyDisr': {}, 'emptyDisqr': {}}]`Additional volumes to be mounted into the database containerstatefulset.extraVolumes[0]dict`{'name': 'data', 'emptyDir': {}, 'emptyDisr': {}, 'emptyDisqr': {}}`statefulset.livenessProbedict`{'enabled': False}`Configure the healthcheck for the databasestatefulset.livenessProbe.enabledbool`False`statefulset.podLabelsdict`{}`The labels to be applied to instances of the databasecolumn navigationevery colum key is link to his line in the values file which ease the process of editing and reaching out the keys using the docuemntation.
example of the link:livenessProbeKeyTypeDefaultDescriptionlivenessProbedict`{'httpGet': {'path': '/healthz', 'port': 'http'}}`livenessProbe.httpGetdict`{'path': '/healthz', 'port': 'http'}`livenessProbe.httpGet.pathstr`/healthz`This is the liveness check endpointlivenessProbe.httpGet.portstr`http`nil valuesIf you would like to define a key for a value, but leave the default empty, you can still specify a description for it
as well as a type. This is possible with both the old and the new comment format:controller:# -- (int) Number of nginx-ingress pods to load balance betweenreplicas:# controller.image -- (string) Number of nginx-ingress pods to load balance betweenimage:This could be useful when wanting to enforce user-defined values for the chart, where there are no sensible defaults.Default values/columnIn cases where you do not want to include the default value fromvalues.yaml, or where the real default is calculated
inside the chart, you can change the contents of the column like so: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 automaticallyannotations:[]Seeherefor an example.Ignoring valuesIn cases you would like to ignore certain values, you can mark it with @ignored tag:# @ignoredservice:port:8080