table-gen

Table Generator: Autogenerate CRD Documentation Tables

Overview

This package contains a tool that automatically generates a documentation table documenting a CRD, and writes it to specified .md files.

Generate Tables

You can run the table generator in two ways:

• Use Makefile (Recommended): Configure your CRD once and generate tables with simple make commands.
• Run from command line: Execute directly with go run for quick testing or ad-hoc documentation.

Use Makefile (Recommended)

Follow the steps:

1. Prepare the parameters' descriptions in the CR's specification file. For example, for the Telemetry CR, prepare the description in operator.kyma-project.io_telemetries.yaml.

2. Set up the table generator in the .md file in which you want to generate the table. Add the TABLE-START and TABLE-END tags in the exact place in the document where you want to generate the table.

      <!-- TABLE-START -->
   
      <!-- TABLE-END -->
   

3. Build the table generator as a binary named table-gen, and add a new target to your module's Makefile that calls this binary. See the following example:

   .PHONY: crd-docs-gen
   crd-docs-gen:
      table-gen --crd-filename ./path/to/your-crd.yaml --md-filename ./docs/user/your-doc.md
      table-gen --crd-filename ./path/to/your-crd-2.yaml --md-filename ./docs/user/your-doc-2.md
      ...
   

   Use the following parameters:

   • --crd-filename: Path to the CRD YAML file
   • --md-filename: Path to the Markdown file where the table will be inserted

   For a complete example, see the Telemetry module's Makefile.

4. In the terminal, run the following command from root:

   make crd-docs-gen
   

   To verify the result, go to the .md files and check that the table has been generated as specified.

Use Command Line

You can also call the table generator from the command line, without needing to add it to the Makefile. To do this, you can either build it and start it, or use go run. See the following example:

go run main.go --crd-filename ../../installation/resources/crds/telemetry/logpipelines.crd.yaml --md-filename ../../docs/05-technical-reference/00-custom-resources/telemetry-01-logpipeline.md