api2md

A Go tool to generate Markdown documentation from Go structs, designed for documenting Kubernetes operator APIs.

Inspired by crd-ref-docs, this tool analyzes your Go files containing Kubernetes API type definitions and generates complete, structured Markdown documentation.

Features

• ✅ Automatic analysis of Go structs in a directory
• ✅ Extraction of documentation comments
• ✅ Support for kubebuilder markers (+kubebuilder:validation:Pattern, +kubebuilder:default, etc.)
• ✅ Generation of links to Kubernetes documentation
• ✅ Support for Kubernetes resource types (CRDs)
• ✅ Flexible configuration via YAML file
• ✅ Single output or per-API-group output mode

Installation

go get -u github.com/golgoth31/api2md

Or clone the repository and build:

git clone https://github.com/golgoth31/api2md.git
cd api2md
go build -o api2md

Usage

Basic usage

api2md \
  --source-path=./api \
  --config=config.yaml \
  --output-path=api.md

Group mode (one file per API group)

api2md \
  --source-path=./api \
  --config=config.yaml \
  --output-path=./docs \
  --output-mode=group

Options

• --source-path: Path to the directory containing Go files with API definitions (required)
• --config: Path to the YAML configuration file (default: config.yaml)
• --output-path: Path to the output Markdown file or directory (default: api.md)
• --output-mode: Output mode: single (one file) or group (one file per group) (default: single)

Configuration

Create a config.yaml file to configure the tool behavior:

processor:
  # Group versions to ignore
  ignoreGroupVersions:
    - "kubecloudscaler.cloud/v1alpha1"
    - "kubecloudscaler.cloud/v1alpha2"
  
  # Types to ignore (RE2 regular expressions)
  ignoreTypes:
    - "(K8s|Gcp)List$"
  
  # Fields to ignore (RE2 regular expressions)
  ignoreFields:
    - "status$"
    - "TypeMeta$"

render:
  # Kubernetes version for generating documentation links
  kubernetesVersion: 1.33

Configuration options

Processor

• ignoreGroupVersions: List of group versions to exclude from documentation
• ignoreTypes: List of regular expressions (RE2) to exclude certain types
• ignoreFields: List of regular expressions (RE2) to exclude certain fields

Render

• kubernetesVersion: Kubernetes version used to generate links to the official documentation

Output format

The tool generates Markdown documentation with:

• Package index: List of all analyzed packages
• Package documentation: Description and types for each package
• Resource types: Identified Kubernetes types (with +kubebuilder:object:root=true)
• Data types: All other types used in the APIs
• Field tables: For each type, a table with:
  • Field name (JSON tag)
  • Type
  • Description (from comments)
  • Default value (from +kubebuilder:default)
  • Validation rules (Pattern, Enum, etc.)
• "Appears in" links: Types that reference this type

Example output

# API Reference

## Packages
- [kubecloudscaler.cloud/common](#kubecloudscalercloudcommon)
- [kubecloudscaler.cloud/v1alpha3](#kubecloudscalercloudv1alpha3)

## kubecloudscaler.cloud/common

Package common contains shared API Schema definitions...

#### ScalerPeriod

ScalerPeriod defines a scaling period with time constraints...

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `type` _string_ |  |  | Enum: [down up] <br /> |
| `time` _[TimePeriod](#timeperiod)_ |  |  |  |
| `minReplicas` _integer_ | Minimum replicas |  |  |

Project structure

api2md/
├── main.go                 # Entry point
├── go.mod                  # Go dependencies
├── config.yaml             # Default configuration
├── internal/
│   ├── config/            # Configuration handling
│   ├── parser/            # Go file parsing
│   └── generator/         # Markdown generation
└── tests_data/            # Test data
    ├── input/             # Sample Go files
    └── output/            # Expected output samples

How it works

1. Parsing: The tool uses go/parser and go/ast to analyze Go files
2. Extraction: It extracts structs, their fields, comments, and kubebuilder markers
3. Filtering: Ignored types and fields are filtered according to the configuration
4. Generation: Markdown documentation is generated from the collected information

Supported kubebuilder markers

• +kubebuilder:object:root=true: Identifies a type as a Kubernetes resource
• +kubebuilder:validation:Pattern=...: Pattern validation rule
• +kubebuilder:validation:Enum=...: Enumeration validation rule
• +kubebuilder:default:=...: Default value
• +optional: Optional field
• +required: Required field

Development

Prerequisites

• Go 1.21 or higher

Tests

go test ./...

Contributing

Contributions are welcome! Feel free to open an issue or a pull request.

License

Apache License 2.0

Inspiration

This tool is inspired by crd-ref-docs by Elastic, but is an independent implementation tailored to the specific needs of Kubernetes API documentation.