@redpanda-data/docs-extensions-and-macros/tools/property-extractor/Makefile

Antora extensions and macros developed for Redpanda documentation.

.PHONY: build venv clean redpanda-git treesitter generate-docs check

# Default tag (can be overridden via `make TAG=v25.1.1`)
TAG       ?= dev

# Derive a “major.minor” or rc identifier from TAG for folder naming
VERSION := $(shell \
  if echo "$(TAG)" | grep -qE '^v?[0-9]+\.[0-9]+'; then \
    echo "$(TAG)" \
      | sed -E 's/^v?([0-9]+\.[0-9]+)(\.[0-9]+)?(-rc[0-9]+)?.*/\1\3/' \
      | sed 's/-rc/rc/'; \
  else \
    echo "$(TAG)"; \
  fi)

# Paths
REPO_ROOT     := $(shell git rev-parse --show-toplevel)
MODULE_ROOT   := $(shell cd "$(dir $(realpath $(lastword $(MAKEFILE_LIST))))"/../.. && pwd)
TOOL_ROOT     := $(MODULE_ROOT)/tools/property-extractor
TMP_ROOT      := $(TOOL_ROOT)/tmp
REDPANDA_SRC  := $(TMP_ROOT)/redpanda
TREESITTER_DIR:= $(TOOL_ROOT)/tree-sitter/tree-sitter-cpp
VENV          := $(TOOL_ROOT)/tmp/redpanda-property-extractor-venv
PYTHON        := $(VENV)/bin/python
OUTPUT_DIR    := $(REPO_ROOT)/autogenerated/$(TAG)/properties
TREE_SITTER   := npx tree-sitter

# --- Main build: venv, fetch code, build parser, extract & docgen ---
build: venv redpanda-git treesitter
	@echo "🔧 Building with Redpanda tag: $(TAG)"
	@mkdir -p $(TOOL_ROOT)/gen
	@cd $(TOOL_ROOT) && \
	  $(PYTHON) -W ignore::FutureWarning property_extractor.py \
	    --recursive \
	    --path $(REDPANDA_SRC) \
	    --output gen/properties-output.json
	@echo "✅ JSON generated at $(TOOL_ROOT)/gen/properties-output.json"
	@$(MAKE) generate-docs

# --- Ensure Python venv & dependencies ---
venv: $(TOOL_ROOT)/requirements.txt
	@if [ ! -d "$(VENV)" ]; then \
	  echo "🐍 Creating virtual environment in $(VENV)..."; \
	  python3 -m venv $(VENV); \
	  $(VENV)/bin/pip install --upgrade pip --quiet; \
	  $(VENV)/bin/pip install --no-cache-dir -r $<; \
	else \
	  echo "🐍 Virtual environment already exists at $(VENV)"; \
	fi

# --- Clean out all generated state ---
clean:
	@echo "🧹 Cleaning up…"
	@rm -rf $(VENV) $(TMP_ROOT) $(REPO_ROOT)/autogenerated

# --- Clone or update Redpanda, checkout TAG or default branch ---
redpanda-git:
	@mkdir -p "$(TMP_ROOT)"
	@echo "🔄 Cloning/updating Redpanda into $(REDPANDA_SRC)…"
	@if [ -d "$(REDPANDA_SRC)" ]; then \
	  git -C "$(REDPANDA_SRC)" fetch --all --tags -q; \
	else \
	  git clone -q https://github.com/redpanda-data/redpanda.git "$(REDPANDA_SRC)"; \
	fi; \
	if git -C "$(REDPANDA_SRC)" rev-parse --verify -q "$(TAG)" >/dev/null; then \
	  echo "🔖 Checking out '$(TAG)'"; \
	  git -C "$(REDPANDA_SRC)" checkout -q "$(TAG)"; \
	else \
	  DEFAULT_BRANCH=$$(git -C "$(REDPANDA_SRC)" symbolic-ref --short refs/remotes/origin/HEAD); \
	  echo "⚠️ Tag '$(TAG)' not found; falling back to '$${DEFAULT_BRANCH}'"; \
	  git -C "$(REDPANDA_SRC)" checkout -q "$${DEFAULT_BRANCH}"; \
	fi

# --- Clone Tree-sitter grammar & generate parser ---
treesitter:
	@echo "🌲 Ensuring tree-sitter-cpp grammar…"
	@if [ ! -d "$(TREESITTER_DIR)" ]; then \
	  git clone https://github.com/tree-sitter/tree-sitter-cpp.git "$(TREESITTER_DIR)"; \
	fi
	@echo "🔧 Generating parser in $(TREESITTER_DIR)…"
	@cd "$(TREESITTER_DIR)" && npm install --silent && $(TREE_SITTER) generate

# --- Turn the JSON into AsciiDoc pages under autogen/<version>/properties ---
generate-docs:
	@echo "📝 Generating AsciiDoc pages in $(OUTPUT_DIR)…"
	@mkdir -p "$(OUTPUT_DIR)"
	@cd $(TOOL_ROOT) && \
	  $(PYTHON) json-to-asciidoc/generate_docs.py --output-dir "$(OUTPUT_DIR)"
	@echo "✅ Docs generated at $(OUTPUT_DIR)"

# --- Debug helper to print all the key paths/vars ---
check:
	@echo "MODULE_ROOT:   $(MODULE_ROOT)"
	@echo "TOOL_ROOT:     $(TOOL_ROOT)"
	@echo "REDPANDA_SRC:  $(REDPANDA_SRC)"
	@echo "TREESITTER:    $(TREESITTER_DIR)"
	@echo "VENV:          $(VENV)"
	@echo "PYTHON:        $(PYTHON)"
	@echo "OUTPUT_DIR:    $(OUTPUT_DIR)"