makefile

# Makefile targets for Sphinx documentation (all targets prefixed with 'docs-')
# Adapted for NeMo Evaluator project structure with pure uv dependency management

.PHONY: docs-html docs-clean docs-live docs-env docs-publish docs-autogen docs-help \
        container-metadata-verify container-metadata-update \
        docs-html-internal docs-html-ga docs-html-ea docs-html-draft \
        docs-live-internal docs-live-ga docs-live-ea docs-live-draft \
        docs-publish-internal docs-publish-ga docs-publish-ea docs-publish-draft \
        update-configs

# Usage:
#   make docs-html DOCS_ENV=internal   # Build docs for internal use
#   make docs-html DOCS_ENV=ga         # Build docs for GA
#   make docs-html                     # Build docs with no special tag
#   make docs-live DOCS_ENV=draft      # Live server with draft tag
#   make docs-publish DOCS_ENV=ga      # Production build (fails on warnings)

DOCS_ENV ?=

# Absolute repository root (directory containing this makefile). This makes doc
# generation robust even when `make` is invoked from a different working dir.
REPO_ROOT := $(abspath $(dir $(lastword $(MAKEFILE_LIST))))

# Container metadata controller inputs (repo-relative)
MAPPING_TOML ?= $(REPO_ROOT)/packages/nemo-evaluator-launcher/src/nemo_evaluator_launcher/resources/mapping.toml
ALL_TASKS_IRS ?= $(REPO_ROOT)/packages/nemo-evaluator-launcher/src/nemo_evaluator_launcher/resources/all_tasks_irs.yaml
README_FILE ?= $(REPO_ROOT)/README.md

# Detect OS for cross-platform compatibility
ifeq ($(OS),Windows_NT)
    RM_CMD = if exist docs\_build rmdir /s /q docs\_build
    DOCS_DIR = docs
    BUILD_DIR = _build\html
else
    RM_CMD = cd docs && rm -rf _build
    DOCS_DIR = docs
    BUILD_DIR = _build/html
endif

# Main documentation targets using uv run from docs/ directory

docs-html:
	@echo "Building HTML documentation..."
	@echo "Note: Autogenerated task documentation will be regenerated automatically during build"
	cd "$(REPO_ROOT)/$(DOCS_DIR)" && uv run --group docs python -m sphinx -b html $(if $(DOCS_ENV),-t $(DOCS_ENV)) . $(BUILD_DIR)

docs-publish:
	@echo "Building HTML documentation for publication (fail on warnings)..."
	@echo "Note: Autogenerated task documentation will be regenerated automatically during build"
	cd "$(REPO_ROOT)/$(DOCS_DIR)" && uv run --group docs python -m sphinx --fail-on-warning --builder html $(if $(DOCS_ENV),-t $(DOCS_ENV)) . $(BUILD_DIR)

docs-clean:
	@echo "Cleaning built documentation..."
	$(RM_CMD)

docs-live:
	@echo "Starting live-reload server (sphinx-autobuild)..."
	@echo "Note: Autogenerated task documentation will be regenerated automatically during build"
	cd "$(REPO_ROOT)/$(DOCS_DIR)" && uv run --group docs python -m sphinx_autobuild --host 0.0.0.0  $(if $(DOCS_ENV),-t $(DOCS_ENV)) . $(BUILD_DIR)

docs-env:
	@echo "Syncing documentation dependencies..."
	cd "$(REPO_ROOT)/$(DOCS_DIR)" && uv sync --group docs
	@echo "Documentation dependencies synced!"
	@echo "You can now run 'make docs-html' or 'make docs-live'"

# ---------------------------------------------------------------------------
# Container metadata helpers
# ---------------------------------------------------------------------------

container-metadata-verify:
	@echo "Verifying container metadata (digests + checksums)..."
	python scripts/container_metadata_controller.py \
		--mapping-toml "$(MAPPING_TOML)" \
		--all-tasks-irs "$(ALL_TASKS_IRS)" \
		--readme-file "$(README_FILE)" \
		verify

container-metadata-update:
	@echo "Updating container metadata (may modify files)..."
	python scripts/container_metadata_controller.py \
		--mapping-toml "$(MAPPING_TOML)" \
		--all-tasks-irs "$(ALL_TASKS_IRS)" \
		--readme-file "$(README_FILE)" \
		update
	@if [ "$$CI" = "true" ]; then \
		echo "CI mode: failing if update produced changes..."; \
		git status --porcelain; \
		test -z "$$(git status --porcelain)"; \
		git diff --exit-code; \
	fi

# HTML build shortcuts

docs-html-internal:
	$(MAKE) docs-html DOCS_ENV=internal

docs-html-ga:
	$(MAKE) docs-html DOCS_ENV=ga

docs-html-ea:
	$(MAKE) docs-html DOCS_ENV=ea

docs-html-draft:
	$(MAKE) docs-html DOCS_ENV=draft

# Publish build shortcuts

docs-publish-internal:
	$(MAKE) docs-publish DOCS_ENV=internal

docs-publish-ga:
	$(MAKE) docs-publish DOCS_ENV=ga

docs-publish-ea:
	$(MAKE) docs-publish DOCS_ENV=ea

docs-publish-draft:
	$(MAKE) docs-publish DOCS_ENV=draft

# Live server shortcuts

docs-live-internal:
	$(MAKE) docs-live DOCS_ENV=internal

docs-live-ga:
	$(MAKE) docs-live DOCS_ENV=ga

docs-live-ea:
	$(MAKE) docs-live DOCS_ENV=ea

docs-live-draft:
	$(MAKE) docs-live DOCS_ENV=draft

# Additional convenience targets

docs-autogen:
	@echo "Regenerating autogenerated task documentation..."
	cd "$(REPO_ROOT)/$(DOCS_DIR)" && uv run --group docs python ../packages/nemo-evaluator-launcher/scripts/autogen_task_yamls.py --docs-root "$(REPO_ROOT)/$(DOCS_DIR)"
	@echo "Task documentation regenerated!"

docs-help:
	@echo "Available documentation targets:"
	@echo "  docs-env        - Sync documentation dependencies with uv"
	@echo "  docs-autogen    - Regenerate autogenerated task documentation"
	@echo "  docs-html       - Build HTML documentation"
	@echo "  docs-live       - Start live-reload server for development"
	@echo "  docs-publish    - Build documentation with strict error checking"
	@echo "  docs-clean      - Clean built documentation"
	@echo ""
	@echo "Environment-specific targets (replace 'html' with 'live' or 'publish'):"
	@echo "  docs-html-internal  - Build with 'internal' tag"
	@echo "  docs-html-ga        - Build with 'ga' tag"
	@echo "  docs-html-ea        - Build with 'ea' tag"
	@echo "  docs-html-draft     - Build with 'draft' tag"
	@echo ""
	@echo "Usage examples:"
	@echo "  make docs-env                    # Sync dependencies first (recommended)"
	@echo "  make docs-autogen                # Regenerate task docs before building"
	@echo "  make docs-html                   # Basic build"
	@echo "  make docs-html DOCS_ENV=ga       # Build with GA tag"
	@echo "  make docs-live DOCS_ENV=draft    # Live server with draft tag"
	@echo ""
	@echo "Note: Uses 'uv run' with dependencies from docs/pyproject.toml"

# ---------------------------------------------------------------------------
# Config consistency checker (requires Claude Code CLI: `claude`)
# ---------------------------------------------------------------------------

NEL_PKG := $(REPO_ROOT)/packages/nemo-evaluator-launcher
CONFIG_REF := $(NEL_PKG)/.claude/plans/config-templates-reference.md

update-configs:
	@cd "$(NEL_PKG)" && \
	DIFF=$$(git diff main...HEAD -- .); \
	if [ -z "$$DIFF" ]; then \
		echo "CONFIGS_OK"; \
	else \
		{ cat "$(CONFIG_REF)"; \
		  printf '\n---\n\nGit diff (main...HEAD):\n\n```diff\n'; \
		  echo "$$DIFF"; \
		  printf '\n```\n'; } \
		| claude -p --model claude-opus-4-6-1m; \
	fi