diff --git a/.github/workflows/build-changelog-gen.yaml b/.github/workflows/build-changelog-gen.yaml index 958b78ab..08dc620d 100644 --- a/.github/workflows/build-changelog-gen.yaml +++ b/.github/workflows/build-changelog-gen.yaml @@ -5,7 +5,7 @@ on: branches: - main paths: - - "changelog-gen/**" + - "tools/changelog-gen/**" - ".github/workflows/build-changelog-gen.yaml" env: @@ -46,7 +46,7 @@ jobs: - name: Build and push Docker image uses: docker/build-push-action@v5 with: - context: ./changelog-gen + context: ./tools/changelog-gen push: true tags: ${{ steps.meta.outputs.tags }} labels: ${{ steps.meta.outputs.labels }} diff --git a/.github/workflows/build-docs-convert.yaml b/.github/workflows/build-docs-convert.yaml index 17843b0a..0b0e7aff 100644 --- a/.github/workflows/build-docs-convert.yaml +++ b/.github/workflows/build-docs-convert.yaml @@ -5,7 +5,7 @@ on: branches: - main paths: - - "docs-convert/**" + - "tools/docs-convert/**" - ".github/workflows/build-docs-convert.yaml" env: @@ -46,7 +46,7 @@ jobs: - name: Build and push Docker image uses: docker/build-push-action@v5 with: - context: ./docs-convert + context: ./tools/docs-convert push: true tags: ${{ steps.meta.outputs.tags }} labels: ${{ steps.meta.outputs.labels }} diff --git a/.github/workflows/build-docs-gen.yaml b/.github/workflows/build-docs-gen.yaml index 9c256cd8..acc6238f 100644 --- a/.github/workflows/build-docs-gen.yaml +++ b/.github/workflows/build-docs-gen.yaml @@ -5,7 +5,7 @@ on: branches: - main paths: - - "docs-gen/**" + - "tools/docs-gen/**" - ".github/workflows/build-docs-gen.yaml" env: @@ -46,7 +46,7 @@ jobs: - name: Build and push Docker image uses: docker/build-push-action@v5 with: - context: ./docs-gen + context: ./tools/docs-gen push: true tags: ${{ steps.meta.outputs.tags }} labels: ${{ steps.meta.outputs.labels }} diff --git a/.github/workflows/build-docs-mint.yaml b/.github/workflows/build-docs-mint.yaml index bb884ffc..0f05c636 100644 --- a/.github/workflows/build-docs-mint.yaml +++ b/.github/workflows/build-docs-mint.yaml @@ -5,7 +5,7 @@ on: branches: - main paths: - - "mintlify/**" + - "tools/mintlify/**" - ".github/workflows/build-docs-mint.yaml" env: @@ -46,7 +46,7 @@ jobs: - name: Build and push Docker image uses: docker/build-push-action@v5 with: - context: ./mintlify + context: ./tools/mintlify push: true tags: ${{ steps.meta.outputs.tags }} labels: ${{ steps.meta.outputs.labels }} diff --git a/.github/workflows/build-mdx-normalize.yaml b/.github/workflows/build-mdx-normalize.yaml index 47fd185e..f419c585 100644 --- a/.github/workflows/build-mdx-normalize.yaml +++ b/.github/workflows/build-mdx-normalize.yaml @@ -5,7 +5,7 @@ on: branches: - main paths: - - "mdx-normalize/**" + - "tools/mdx-normalize/**" - ".github/workflows/build-mdx-normalize.yaml" env: @@ -46,7 +46,7 @@ jobs: - name: Build and push Docker image uses: docker/build-push-action@v5 with: - context: ./mdx-normalize + context: ./tools/mdx-normalize push: true tags: ${{ steps.meta.outputs.tags }} labels: ${{ steps.meta.outputs.labels }} diff --git a/.github/workflows/build-omni-cli-gen.yaml b/.github/workflows/build-omni-cli-gen.yaml index 53bbcded..c720cd21 100644 --- a/.github/workflows/build-omni-cli-gen.yaml +++ b/.github/workflows/build-omni-cli-gen.yaml @@ -5,7 +5,7 @@ on: branches: - main paths: - - "omni-cli-gen/**" + - "tools/omni-cli-gen/**" - ".github/workflows/build-omni-cli-gen.yaml" env: @@ -46,7 +46,7 @@ jobs: - name: Build and push Docker image uses: docker/build-push-action@v5 with: - context: ./omni-cli-gen + context: ./tools/omni-cli-gen push: true tags: ${{ steps.meta.outputs.tags }} labels: ${{ steps.meta.outputs.labels }} diff --git a/.github/workflows/build-omni-config-gen.yaml b/.github/workflows/build-omni-config-gen.yaml index 15838d05..ea358825 100644 --- a/.github/workflows/build-omni-config-gen.yaml +++ b/.github/workflows/build-omni-config-gen.yaml @@ -5,7 +5,7 @@ on: branches: - main paths: - - "omni-config-gen/**" + - "tools/omni-config-gen/**" - ".github/workflows/build-omni-config-gen.yaml" env: @@ -46,7 +46,7 @@ jobs: - name: Build and push Docker image uses: docker/build-push-action@v5 with: - context: ./omni-config-gen + context: ./tools/omni-config-gen push: true tags: ${{ steps.meta.outputs.tags }} labels: ${{ steps.meta.outputs.labels }} diff --git a/.github/workflows/build-version-upgrade-gen.yaml b/.github/workflows/build-version-upgrade-gen.yaml index 46b44852..ae075a24 100644 --- a/.github/workflows/build-version-upgrade-gen.yaml +++ b/.github/workflows/build-version-upgrade-gen.yaml @@ -5,7 +5,7 @@ on: branches: - main paths: - - "version-upgrade-gen/**" + - "tools/version-upgrade-gen/**" - ".github/workflows/build-version-upgrade-gen.yaml" env: @@ -46,7 +46,7 @@ jobs: - name: Build and push Docker image uses: docker/build-push-action@v5 with: - context: ./version-upgrade-gen + context: ./tools/version-upgrade-gen push: true tags: ${{ steps.meta.outputs.tags }} labels: ${{ steps.meta.outputs.labels }} diff --git a/.github/workflows/docs-ci.yaml b/.github/workflows/docs-ci.yaml index de5aec45..2e0b165e 100644 --- a/.github/workflows/docs-ci.yaml +++ b/.github/workflows/docs-ci.yaml @@ -10,7 +10,7 @@ on: - "**/*.mdx" - "**/*.yaml" - "Makefile" - - "docs-validate/**" + - "tools/docs-validate/**" jobs: docs-checks: runs-on: ubuntu-latest diff --git a/.github/workflows/sync-omni-config-reference.yaml b/.github/workflows/sync-omni-config-reference.yaml index d1af2736..caf558fe 100644 --- a/.github/workflows/sync-omni-config-reference.yaml +++ b/.github/workflows/sync-omni-config-reference.yaml @@ -20,7 +20,7 @@ jobs: - name: Install Go uses: actions/setup-go@v6 with: - go-version-file: omni-config-gen/go.mod + go-version-file: tools/omni-config-gen/go.mod cache: false - name: Regenerate Omni configuration reference run: | diff --git a/.gitignore b/.gitignore index 5fd00c81..64b5b3e4 100644 --- a/.gitignore +++ b/.gitignore @@ -1,5 +1,5 @@ # Generated documentation files -docs-convert/docs/ +tools/docs-convert/docs/ _out/ # Local Netlify folder @@ -9,10 +9,10 @@ _out/ .upgrade-version-tmp # Go build artifacts (compiled binary in each tool dir, named after the dir) -version-upgrade-gen/version-upgrade-gen -changelog-gen/changelog-gen -docs-gen/docs-gen -docs-convert/docs-convert -docs-validate/docs-validate -mdx-normalize/mdx-normalize -omni-config-gen/omni-config-gen +tools/version-upgrade-gen/version-upgrade-gen +tools/changelog-gen/changelog-gen +tools/docs-gen/docs-gen +tools/docs-convert/docs-convert +tools/docs-validate/docs-validate +tools/mdx-normalize/mdx-normalize +tools/omni-config-gen/omni-config-gen diff --git a/CLAUDE.md b/CLAUDE.md deleted file mode 100644 index 1b264fd0..00000000 --- a/CLAUDE.md +++ /dev/null @@ -1,219 +0,0 @@ -# CLAUDE.md - -This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. - -## Project Overview - -This repository contains the documentation for Siderolabs products, particularly Omni - a Kubernetes management platform and Talos - a Linux operating system for Kubernetes. The documentation is built using Mintlify and configured via `docs.json`. - -## Architecture - -### Documentation Structure -- **Single documentation site**: All docs are organized under the `omni/`, `talos/`, and `kubernetes` directories. -- **Mintlify-based**: Uses Mintlify documentation platform with configuration in `docs.json` -- **MDX format**: All documentation files use `.mdx` extension for enhanced markdown with React components -- **Hierarchical organization**: Content is organized into logical groups (Overview, Getting Started, Infrastructure, etc.) - -### Key Directories -- `omni/overview/` - High-level product information -- `omni/getting-started/` - User onboarding guides -- `omni/infrastructure-and-extensions/` - Infrastructure setup and extensions -- `omni/omni-cluster-setup/` - Cluster configuration guides -- `omni/cluster-management/` - Ongoing cluster operations -- `omni/security-and-authentication/` - Security and auth configuration -- `omni/reference/` - Reference documentation -- `images/` - Static assets and screenshots - -### Navigation Configuration -The site navigation is entirely defined in `docs.json` with a tab-based structure. All pages must be explicitly listed in the navigation configuration to appear in the documentation site. - -## Content Standards - -### File Naming -- Use kebab-case for file and directory names -- All documentation files use `.mdx` extension -- Image files are organized in `images/` subdirectories within relevant sections - -### Documentation Structure -- Each `.mdx` file begins with YAML frontmatter containing at minimum a `title` field -- Content focuses on Omni platform usage, Kubernetes cluster management, and Talos Linux integration -- Includes step-by-step guides with screenshots stored in adjacent `images/` directories - -## Development Workflow - -### Local Development with Docker -To preview the documentation locally without installing Mintlify, use the provided Makefile: - -```bash -# Build container and start preview server -make preview - -# View available commands -make help -``` - -Alternatively, use Docker commands directly: -```bash -# Build the Docker image -docker build -t mintlify-docs . - -# Run the development server (mounts current directory) -docker run -p 3000:3000 -v $(pwd):/docs mintlify-docs -``` - -Access the site at http://localhost:3000 - -### Generating docs.json -The `docs.json` file is automatically generated from multiple YAML config files using a containerized generator: - -```bash -# Generate and validate docs.json using container (recommended) -make docs.json - -# Check for MDX files not included in configuration -make check-missing - -# Build the docs-gen container locally (if needed) -make build-docs-gen - -# Alternative: Use local Go build for development -make docs.json-local -make check-missing-local -make generate-deps # Install Go dependencies -``` - -The generator supports **multi-file configuration** - it merges multiple YAML files where: -- **Base configuration**: First file provides site metadata (colors, branding, etc.) -- **Navigation tabs**: All `navigation.tabs` from all files are combined in order -- **Icon support**: Tabs can specify icons with the `icon` field - -**Schema validation is enabled by default** and validates against the Mintlify schema. Use `make check-missing` to find any documentation files that aren't included in the navigation. - -### Making Changes -1. Edit `.mdx` files directly for content updates -2. Update YAML config files: - - `common.yaml` for site metadata (colors, branding, global navigation) - - `omni.yaml` for Omni-specific navigation tabs - - Additional YAML files for other product tabs -3. Run `make docs.json` to regenerate the configuration -4. Add images to appropriate `images/` subdirectories -5. Use Docker setup above to preview changes locally - -### Multi-File Configuration -The generator merges YAML files in the order specified: -```bash -# Using container (recommended) -docker run --rm -v $(PWD):/workspace -w /workspace ghcr.io/siderolabs/docs-gen:latest common.yaml omni.yaml additional-tabs.yaml - -# Using local Go build -cd docs-gen && go run main.go ../common.yaml ../omni.yaml ../additional-tabs.yaml -``` - -Example tab with icon: -```yaml -navigation: - tabs: - - tab: "Product Name" - icon: "/images/product.svg" # or FontAwesome icon name - groups: - - group: "Getting Started" - folder: "product/getting-started" -``` - -### Manual Page Configuration -The generator supports two approaches for page organization: - -**Option 1: Automatic folder scanning (current default)** -```yaml -navigation: - tabs: - - tab: "Docs" - groups: - - group: "Getting Started" - folder: "docs/getting-started" - order: # Optional custom ordering - - "intro.mdx" - - "setup.mdx" -``` - -**Option 2: Manual page definition (NEW)** -```yaml -navigation: - tabs: - - tab: "Docs" - groups: - - group: "Security and Authentication" - folder: "omni/security-and-authentication" # Optional base path - pages: - - "authentication-and-authorization" - - "how-to-manage-acls" - - "omni-kms-disk-encryption" - - group: "Rotate Siderolink Join Token" - pages: - - "rotate-siderolink-join-token/rotate-siderolink-join-token" - - group: "Using SAML With Omni" - pages: - - "using-saml-with-omni/auto-assign-roles-to-saml-users" - - "using-saml-with-omni/configure-saml-and-acls" - - "using-saml-with-omni/how-to-configure-entraid-for-omni" - - "using-saml-with-omni/overview" -``` - -**Key features of manual page configuration:** -- **Mixed content**: Can combine individual pages and subgroups -- **Nested subgroups**: Subgroups can contain other subgroups -- **Base path**: Optional `folder` field prepends to all page paths -- **Flexible structure**: Full control over navigation hierarchy -- **Backward compatible**: Falls back to folder scanning if no `pages` defined - -### Content Guidelines -- Focus on practical, actionable guidance for Omni users -- Include screenshots for UI-based procedures -- Maintain consistency with existing documentation structure and tone -- All content relates to Kubernetes management, infrastructure setup, or security configuration - -## Important Notes - -- **Containerized generator**: The `docs.json` file is generated using a containerized tool (`ghcr.io/siderolabs/docs-gen`) -- **Multi-file configuration**: Generated from multiple YAML files - edit the YAML files, not the JSON directly -- **Automatic page discovery**: The generator automatically discovers all `.mdx` files in configured folders -- **CI/CD integration**: The container is built and published automatically via GitHub Actions -- **Mintlify hosting**: The site is hosted and built by Mintlify using the `docs.json` configuration -- **Static assets**: All images are committed to the repository in `images/` directories - -## Generator Configuration - -### Code Structure -- **`docs-gen/`**: Contains the Go generator code - - `main.go`: Main generator logic - - `go.mod`, `go.sum`: Go module files -- **YAML config files**: In root directory (e.g., `common.yaml`, `omni.yaml`) - -### Configuration Files -The YAML config files control: -- **Site metadata**: name, colors, logos, banners -- **Schema validation**: URL for Mintlify JSON schema validation -- **Navigation structure**: tabs, groups, and folder mappings -- **Page ordering**: optional custom ordering within groups -- **Global navigation**: footer links, external anchors -- **Redirects**: URL redirects for moved or renamed pages - -Each navigation group maps to a folder, and all `.mdx` files in that folder are automatically included. Subdirectories become nested groups. - -### Schema Validation -The generator validates the output against the Mintlify schema by default. To skip validation (not recommended), use: -```bash -go run main.go --skip-validation common.yaml > docs.json -``` - -### Redirects -Add redirects to handle moved or renamed pages: -```yaml -redirects: - - source: "/old-path" - destination: "/new-path" - - source: "/legacy-docs/*" - destination: "/docs/$1" -``` - -Redirects support wildcards (`*`) and parameter substitution (`$1`, `$2`, etc.) as described in the [Mintlify redirects documentation](https://mintlify.com/docs/settings/broken-links#redirects). diff --git a/Makefile b/Makefile index 26b210a5..f5dff8e1 100644 --- a/Makefile +++ b/Makefile @@ -54,10 +54,13 @@ help: ## Show this help message .PHONY: build-mint build-mint: ## Build the Mintlify documentation container locally - docker build -t $(MINT_IMAGE) ./mintlify + docker build -t $(MINT_IMAGE) ./tools/mintlify .PHONY: docs-preview preview -docs-preview: ## Build and run the documentation preview server +docs-preview: ## Build and run the documentation preview server (style-checks changed docs first) + @echo "==> Style-checking changed/new docs before preview..." + -@$(MAKE) --no-print-directory style-check-changed-auto + @echo "" docker run --rm -it \ --name $(CONTAINER_NAME) \ -p $(PORT):$(PORT) \ @@ -88,20 +91,20 @@ docs.json: common.yaml omni.yaml ## Generate and validate docs.json from multipl changelog.yaml \ > public/docs.json -docs.json-local: common.yaml omni.yaml docs-gen/main.go ## Generate docs.json using local Go build - cd docs-gen && go run . \ - ../common.yaml \ - ../talos-v1.13.yaml \ - ../talos-v1.12.yaml \ - ../talos-v1.11.yaml \ - ../talos-v1.10.yaml \ - ../talos-v1.9.yaml \ - ../talos-v1.8.yaml \ - ../talos-v1.7.yaml \ - ../omni.yaml \ - ../kubernetes-guides.yaml \ - ../changelog.yaml \ - > ../public/docs.json +docs.json-local: common.yaml omni.yaml tools/docs-gen/main.go ## Generate docs.json using local Go build + cd tools/docs-gen && go run . \ + ../../common.yaml \ + ../../talos-v1.13.yaml \ + ../../talos-v1.12.yaml \ + ../../talos-v1.11.yaml \ + ../../talos-v1.10.yaml \ + ../../talos-v1.9.yaml \ + ../../talos-v1.8.yaml \ + ../../talos-v1.7.yaml \ + ../../omni.yaml \ + ../../kubernetes-guides.yaml \ + ../../changelog.yaml \ + > ../../public/docs.json .PHONY: check-missing check-missing: ## Check for MDX files not included in config files @@ -120,43 +123,43 @@ check-missing: ## Check for MDX files not included in config files .PHONY: check-missing-local check-missing-local: ## Check for missing files using local Go build - cd docs-gen && go run . --detect-missing \ - ../common.yaml \ - ../talos-v1.13.yaml \ - ../talos-v1.12.yaml \ - ../talos-v1.11.yaml \ - ../talos-v1.10.yaml \ - ../talos-v1.9.yaml \ - ../talos-v1.8.yaml \ - ../talos-v1.7.yaml \ - ../omni.yaml \ - ../kubernetes-guides.yaml \ - ../changelog.yaml + cd tools/docs-gen && go run . --detect-missing \ + ../../common.yaml \ + ../../talos-v1.13.yaml \ + ../../talos-v1.12.yaml \ + ../../talos-v1.11.yaml \ + ../../talos-v1.10.yaml \ + ../../talos-v1.9.yaml \ + ../../talos-v1.8.yaml \ + ../../talos-v1.7.yaml \ + ../../omni.yaml \ + ../../kubernetes-guides.yaml \ + ../../changelog.yaml .PHONY: generate-deps generate-deps: ## Install Go dependencies for the generator - cd docs-gen && go mod tidy + cd tools/docs-gen && go mod tidy .PHONY: build-docs-gen-container build-docs-gen-container: ## Build the docs-gen container locally - docker build -t $(DOCS_GEN_IMAGE) ./docs-gen + docker build -t $(DOCS_GEN_IMAGE) ./tools/docs-gen .PHONY: build-docs-convert-container build-docs-convert-container: ## Build the docs-convert container locally - docker build -t $(DOCS_CONVERT_IMAGE) ./docs-convert + docker build -t $(DOCS_CONVERT_IMAGE) ./tools/docs-convert .PHONY: test-docs-gen test-docs-gen: ## Run tests for the docs-gen utility - cd docs-gen && go test -v + cd tools/docs-gen && go test -v .PHONY: test-docs-gen-coverage test-docs-gen-coverage: ## Run tests with coverage report - cd docs-gen && go test -v -coverprofile=coverage.out \ + cd tools/docs-gen && go test -v -coverprofile=coverage.out \ && go tool cover -html=coverage.out -o coverage.html .PHONY: test-docs-gen-race test-docs-gen-race: ## Run tests with race detection - cd docs-gen && go test -v -race + cd tools/docs-gen && go test -v -race .PHONY: test-all test-all: test-docs-gen ## Run all tests @@ -229,7 +232,7 @@ generate-talos-reference-local: ## Generate Talos reference docs using local Go mkdir -p _out/docs docker run --rm --platform=$(TALOSCTL_PLATFORM) -u $(shell id -u):$(shell id -g) -v $(PWD)/_out/docs:/docs $(TALOSCTL_IMAGE) docs /docs @echo "Converting generated docs to MDX..." - cd docs-convert && go run main.go ../_out/docs ../public/talos/$(TALOS_VERSION)/reference/configuration/ + cd tools/docs-convert && go run main.go ../../_out/docs ../../public/talos/$(TALOS_VERSION)/reference/configuration/ @echo "Reference documentation generated in public/talos/$(TALOS_VERSION)/reference/configuration/" OMNI_CONFIG_SCHEMA_URL ?= https://raw.githubusercontent.com/siderolabs/omni/refs/heads/main/internal/pkg/config/schema.json @@ -253,15 +256,15 @@ pull_if_missing = docker image inspect $(1) >/dev/null 2>&1 || docker pull $(1) .PHONY: build-omni-cli-gen-container build-omni-cli-gen-container: ## Build the omni-cli-gen container locally - docker build -t $(OMNI_CLI_GEN_IMAGE) ./omni-cli-gen + docker build -t $(OMNI_CLI_GEN_IMAGE) ./tools/omni-cli-gen .PHONY: build-omni-config-gen-container build-omni-config-gen-container: ## Build the omni-config-gen container locally - docker build -t $(OMNI_CONFIG_GEN_IMAGE) ./omni-config-gen + docker build -t $(OMNI_CONFIG_GEN_IMAGE) ./tools/omni-config-gen .PHONY: build-mdx-normalize-container build-mdx-normalize-container: ## Build the mdx-normalize container locally - docker build -t $(MDX_NORMALIZE_IMAGE) ./mdx-normalize + docker build -t $(MDX_NORMALIZE_IMAGE) ./tools/mdx-normalize # ---- Normalization --------------------------------------------------------- @@ -273,8 +276,8 @@ normalize-doc: ## Normalize the generated Omni reference .mdx files for Mintlify .PHONY: normalize-doc-local normalize-doc-local: ## Normalize the generated Omni reference .mdx files using local Go build - @if [ -f $(OMNI_CLI_REF_PATH) ]; then cd mdx-normalize && go run . ../$(OMNI_CLI_REF_PATH); fi - @if [ -f $(IMAGE_FACTORY_REF_PATH) ]; then cd mdx-normalize && go run . --strip-hr ../$(IMAGE_FACTORY_REF_PATH); fi + @if [ -f $(OMNI_CLI_REF_PATH) ]; then cd tools/mdx-normalize && go run . ../../$(OMNI_CLI_REF_PATH); fi + @if [ -f $(IMAGE_FACTORY_REF_PATH) ]; then cd tools/mdx-normalize && go run . --strip-hr ../../$(IMAGE_FACTORY_REF_PATH); fi # ---- omnictl CLI reference ------------------------------------------------- @@ -328,7 +331,7 @@ generate-omni-config-reference: ## Generate Omni configuration reference docs fr .PHONY: generate-omni-config-reference-local generate-omni-config-reference-local: ## Generate Omni configuration reference docs using local Go build @echo "Generating Omni configuration reference..." - cd omni-config-gen && go run . $(OMNI_CONFIG_SCHEMA_URL) > ../$(OMNI_CONFIG_REF_PATH).tmp && mv ../$(OMNI_CONFIG_REF_PATH).tmp ../$(OMNI_CONFIG_REF_PATH) || { rm -f ../$(OMNI_CONFIG_REF_PATH).tmp; exit 1; } + cd tools/omni-config-gen && go run . $(OMNI_CONFIG_SCHEMA_URL) > ../../$(OMNI_CONFIG_REF_PATH).tmp && mv ../../$(OMNI_CONFIG_REF_PATH).tmp ../../$(OMNI_CONFIG_REF_PATH) || { rm -f ../../$(OMNI_CONFIG_REF_PATH).tmp; exit 1; } @echo "Reference documentation generated at $(OMNI_CONFIG_REF_PATH)" # ---- Image Factory configuration reference --------------------------------- @@ -378,11 +381,11 @@ changelog: ## Generate the changelog from GitHub releases .PHONY: changelog-local changelog-local: ## Generate the changelog using local Go build - cd changelog-gen && go run . --output ../public/changelog.mdx + cd tools/changelog-gen && go run . --output ../../public/changelog.mdx .PHONY: validate-docs-nav validate-docs-nav: ## Validate all talos yaml nav configs match their content directories - cd docs-validate && go run . --workspace .. + cd tools/docs-validate && go run . --workspace ../.. # validate-tag distinguishes the two ways a TAG can be wrong, with a tailored # message for each, and fails BEFORE the generator writes anything: @@ -422,7 +425,7 @@ upgrade-talos-version: ## Upgrade Talos docs to a release tag: make upgrade-talo upgrade-talos-version-local: ## Same as upgrade-talos-version but using the local Go build @test -n "$(TAG)" || { echo "Error: TAG is required, e.g. make upgrade-talos-version-local TAG=v1.14.0-beta.0"; exit 1; } $(validate-tag) - cd version-upgrade-gen && go run . --workspace .. --tag $(TAG) + cd tools/version-upgrade-gen && go run . --workspace ../.. --tag $(TAG) $(eval NEW_VERSION := $(shell cat .upgrade-version-tmp 2>/dev/null)) @rm -f .upgrade-version-tmp $(MAKE) generate-talos-reference-local @@ -434,7 +437,7 @@ upgrade-talos-version-local: ## Same as upgrade-talos-version but using the loca .PHONY: build-version-upgrade-container build-version-upgrade-container: ## Build the version-upgrade-gen container locally - docker build -t $(VERSION_UPGRADE_IMAGE) ./version-upgrade-gen + docker build -t $(VERSION_UPGRADE_IMAGE) ./tools/version-upgrade-gen # ---- Style guide checker --------------------------------------------------- @@ -448,7 +451,7 @@ style-check: ## Check docs against the style guide (container). Scope with DOC=p .PHONY: style-check-local style-check-local: ## Check docs against the style guide using local Go build. Scope with DOC=public/path - @cd style-guide-checker && go run . $(STYLE_CHECK_ARGS) ../$(if $(DOC),$(DOC),public) + @cd tools/style-guide-checker && go run . $(STYLE_CHECK_ARGS) ../../$(if $(DOC),$(DOC),public) # Git ref the "changed" target diffs against. Locally, HEAD catches your # working-tree edits; in CI set this to the PR base, e.g. STYLE_CHECK_BASE=origin/main. @@ -473,7 +476,7 @@ style-check-changed-local: ## Check changed .mdx files using local Go build. Bas exit 0; \ fi; \ echo "Checking changed files:" $$files; \ - cd style-guide-checker && go run . $(STYLE_CHECK_ARGS) $$(for f in $$files; do echo "../$$f"; done) + cd tools/style-guide-checker && go run . $(STYLE_CHECK_ARGS) $$(for f in $$files; do echo "../../$$f"; done) .PHONY: style-check-changed-auto style-check-changed-auto: ## Check changed .mdx files, preferring local Go and falling back to the container. @@ -484,10 +487,10 @@ style-check-changed-auto: ## Check changed .mdx files, preferring local Go and f fi; \ echo "Checking changed files:" $$files; \ if command -v go >/dev/null 2>&1; then \ - cd style-guide-checker && go run . $(STYLE_CHECK_ARGS) $$(for f in $$files; do echo "../$$f"; done); \ + cd tools/style-guide-checker && go run . $(STYLE_CHECK_ARGS) $$(for f in $$files; do echo "../../$$f"; done); \ elif command -v docker >/dev/null 2>&1; then \ echo "(go not found — using the container)"; \ - docker image inspect $(STYLE_CHECK_IMAGE) >/dev/null 2>&1 || docker build -q -t $(STYLE_CHECK_IMAGE) ./style-guide-checker >/dev/null; \ + docker image inspect $(STYLE_CHECK_IMAGE) >/dev/null 2>&1 || docker build -q -t $(STYLE_CHECK_IMAGE) ./tools/style-guide-checker >/dev/null; \ docker run --rm -v $(PWD):/workspace -w /workspace $(STYLE_CHECK_IMAGE) $(STYLE_CHECK_ARGS) $$files; \ else \ echo "Skipping style check: neither go nor docker is available."; \ @@ -495,4 +498,4 @@ style-check-changed-auto: ## Check changed .mdx files, preferring local Go and f .PHONY: build-style-check-container build-style-check-container: ## Build the style-guide-checker container locally - docker build -t $(STYLE_CHECK_IMAGE) ./style-guide-checker + docker build -t $(STYLE_CHECK_IMAGE) ./tools/style-guide-checker diff --git a/contributing-guides/generating-docs.md b/contributing-guides/generating-docs.md index 30815f95..6c3ffee8 100644 --- a/contributing-guides/generating-docs.md +++ b/contributing-guides/generating-docs.md @@ -34,7 +34,7 @@ How it works: 1. `talosctl docs` runs from the official `ghcr.io/siderolabs/talosctl` image and writes Markdown into a temporary `_out/docs` directory. -2. The [`docs-convert`](../docs-convert/README.md) tool converts that Markdown +2. The [`docs-convert`](../tools/docs-convert/README.md) tool converts that Markdown into Mintlify-flavored MDX in the output directory. Targets: @@ -59,7 +59,7 @@ make upgrade-talos-version TAG=v1.14.0 # stable make upgrade-talos-version-local TAG=v1.14.0 # same, using the local Go build ``` -See [`version-upgrade-gen/README.md`](../version-upgrade-gen/README.md) for the full details. +See [`version-upgrade-gen/README.md`](../tools/version-upgrade-gen/README.md) for the full details. ## Omni reference @@ -104,7 +104,7 @@ make build-mdx-normalize-container ### Normalization -Raw generator output contains constructs that Mintlify (which parses `.mdx` as MDX/JSX) does not render correctly. The CLI and Image Factory pages are cleaned up by [`mdx-normalize`](../mdx-normalize/README.md), which: +Raw generator output contains constructs that Mintlify (which parses `.mdx` as MDX/JSX) does not render correctly. The CLI and Image Factory pages are cleaned up by [`mdx-normalize`](../tools/mdx-normalize/README.md), which: - converts tab-indented code blocks into fenced code blocks, - keeps tab-indented "Synopsis" prose as normal paragraphs, @@ -130,10 +130,10 @@ Each generator lives in its own directory with a `Dockerfile`, and most also hav | Directory | Role | Image ownership | | --- | --- | --- | -| [`docs-convert/`](../docs-convert/README.md) | Talos Markdown → MDX | this repo | -| [`omni-cli-gen/`](../omni-cli-gen/README.md) | packages a pinned `omnictl` | this repo (docs helper) | -| [`omni-config-gen/`](../omni-config-gen/README.md) | Omni config reference from the JSON schema | this repo | -| [`mdx-normalize/`](../mdx-normalize/README.md) | normalizes generated MDX for Mintlify | this repo | +| [`docs-convert/`](../tools/docs-convert/README.md) | Talos Markdown → MDX | this repo | +| [`omni-cli-gen/`](../tools/omni-cli-gen/README.md) | packages a pinned `omnictl` | this repo (docs helper) | +| [`omni-config-gen/`](../tools/omni-config-gen/README.md) | Omni config reference from the JSON schema | this repo | +| [`mdx-normalize/`](../tools/mdx-normalize/README.md) | normalizes generated MDX for Mintlify | this repo | | `changelog-gen/` | changelog from GitHub releases | this repo | `talosctl` is consumed from Siderolabs' **official** image; the rest are docs-repo tooling. diff --git a/changelog-gen/Dockerfile b/tools/changelog-gen/Dockerfile similarity index 100% rename from changelog-gen/Dockerfile rename to tools/changelog-gen/Dockerfile diff --git a/changelog-gen/go.mod b/tools/changelog-gen/go.mod similarity index 100% rename from changelog-gen/go.mod rename to tools/changelog-gen/go.mod diff --git a/changelog-gen/main.go b/tools/changelog-gen/main.go similarity index 100% rename from changelog-gen/main.go rename to tools/changelog-gen/main.go diff --git a/docs-convert/Dockerfile b/tools/docs-convert/Dockerfile similarity index 100% rename from docs-convert/Dockerfile rename to tools/docs-convert/Dockerfile diff --git a/docs-convert/README.md b/tools/docs-convert/README.md similarity index 100% rename from docs-convert/README.md rename to tools/docs-convert/README.md diff --git a/docs-convert/go.mod b/tools/docs-convert/go.mod similarity index 100% rename from docs-convert/go.mod rename to tools/docs-convert/go.mod diff --git a/docs-convert/main.go b/tools/docs-convert/main.go similarity index 100% rename from docs-convert/main.go rename to tools/docs-convert/main.go diff --git a/docs-convert/main_test.go b/tools/docs-convert/main_test.go similarity index 100% rename from docs-convert/main_test.go rename to tools/docs-convert/main_test.go diff --git a/docs-gen/Dockerfile b/tools/docs-gen/Dockerfile similarity index 100% rename from docs-gen/Dockerfile rename to tools/docs-gen/Dockerfile diff --git a/docs-gen/README.md b/tools/docs-gen/README.md similarity index 100% rename from docs-gen/README.md rename to tools/docs-gen/README.md diff --git a/docs-gen/go.mod b/tools/docs-gen/go.mod similarity index 100% rename from docs-gen/go.mod rename to tools/docs-gen/go.mod diff --git a/docs-gen/go.sum b/tools/docs-gen/go.sum similarity index 100% rename from docs-gen/go.sum rename to tools/docs-gen/go.sum diff --git a/docs-gen/main.go b/tools/docs-gen/main.go similarity index 100% rename from docs-gen/main.go rename to tools/docs-gen/main.go diff --git a/docs-gen/main_test.go b/tools/docs-gen/main_test.go similarity index 100% rename from docs-gen/main_test.go rename to tools/docs-gen/main_test.go diff --git a/docs-validate/README.md b/tools/docs-validate/README.md similarity index 97% rename from docs-validate/README.md rename to tools/docs-validate/README.md index a8ffa519..64fa664c 100644 --- a/docs-validate/README.md +++ b/tools/docs-validate/README.md @@ -15,7 +15,7 @@ It reports a per-version summary and exits with a non-zero status if any issues ```bash # Run across all versions -make validate-talos-docs +make validate-docs-nav ``` Example output: diff --git a/docs-validate/docs-validate b/tools/docs-validate/docs-validate similarity index 85% rename from docs-validate/docs-validate rename to tools/docs-validate/docs-validate index f89a9662..f5724827 100755 Binary files a/docs-validate/docs-validate and b/tools/docs-validate/docs-validate differ diff --git a/docs-validate/go.mod b/tools/docs-validate/go.mod similarity index 100% rename from docs-validate/go.mod rename to tools/docs-validate/go.mod diff --git a/docs-validate/go.sum b/tools/docs-validate/go.sum similarity index 100% rename from docs-validate/go.sum rename to tools/docs-validate/go.sum diff --git a/docs-validate/main.go b/tools/docs-validate/main.go similarity index 100% rename from docs-validate/main.go rename to tools/docs-validate/main.go diff --git a/mdx-normalize/Dockerfile b/tools/mdx-normalize/Dockerfile similarity index 100% rename from mdx-normalize/Dockerfile rename to tools/mdx-normalize/Dockerfile diff --git a/mdx-normalize/README.md b/tools/mdx-normalize/README.md similarity index 100% rename from mdx-normalize/README.md rename to tools/mdx-normalize/README.md diff --git a/mdx-normalize/go.mod b/tools/mdx-normalize/go.mod similarity index 100% rename from mdx-normalize/go.mod rename to tools/mdx-normalize/go.mod diff --git a/mdx-normalize/main.go b/tools/mdx-normalize/main.go similarity index 100% rename from mdx-normalize/main.go rename to tools/mdx-normalize/main.go diff --git a/mdx-normalize/main_test.go b/tools/mdx-normalize/main_test.go similarity index 100% rename from mdx-normalize/main_test.go rename to tools/mdx-normalize/main_test.go diff --git a/mintlify/Dockerfile b/tools/mintlify/Dockerfile similarity index 100% rename from mintlify/Dockerfile rename to tools/mintlify/Dockerfile diff --git a/mintlify/README.md b/tools/mintlify/README.md similarity index 90% rename from mintlify/README.md rename to tools/mintlify/README.md index 1f53953b..35f12ded 100644 --- a/mintlify/README.md +++ b/tools/mintlify/README.md @@ -8,4 +8,4 @@ If Mintlify build and maintain their own published container we can drop this pa ## Updating mintlify container -In order to update the mintlify container you have to make changes to a file in the mintlify/ folder. +In order to update the mintlify container you have to make changes to a file in the tools/mintlify/ folder. diff --git a/omni-cli-gen/Dockerfile b/tools/omni-cli-gen/Dockerfile similarity index 100% rename from omni-cli-gen/Dockerfile rename to tools/omni-cli-gen/Dockerfile diff --git a/omni-cli-gen/README.md b/tools/omni-cli-gen/README.md similarity index 100% rename from omni-cli-gen/README.md rename to tools/omni-cli-gen/README.md diff --git a/omni-config-gen/.gitignore b/tools/omni-config-gen/.gitignore similarity index 100% rename from omni-config-gen/.gitignore rename to tools/omni-config-gen/.gitignore diff --git a/omni-config-gen/Dockerfile b/tools/omni-config-gen/Dockerfile similarity index 100% rename from omni-config-gen/Dockerfile rename to tools/omni-config-gen/Dockerfile diff --git a/omni-config-gen/README.md b/tools/omni-config-gen/README.md similarity index 100% rename from omni-config-gen/README.md rename to tools/omni-config-gen/README.md diff --git a/omni-config-gen/go.mod b/tools/omni-config-gen/go.mod similarity index 100% rename from omni-config-gen/go.mod rename to tools/omni-config-gen/go.mod diff --git a/omni-config-gen/main.go b/tools/omni-config-gen/main.go similarity index 100% rename from omni-config-gen/main.go rename to tools/omni-config-gen/main.go diff --git a/style-guide-checker/Dockerfile b/tools/style-guide-checker/Dockerfile similarity index 100% rename from style-guide-checker/Dockerfile rename to tools/style-guide-checker/Dockerfile diff --git a/style-guide-checker/README.md b/tools/style-guide-checker/README.md similarity index 100% rename from style-guide-checker/README.md rename to tools/style-guide-checker/README.md diff --git a/style-guide-checker/exceptions.txt b/tools/style-guide-checker/exceptions.txt similarity index 100% rename from style-guide-checker/exceptions.txt rename to tools/style-guide-checker/exceptions.txt diff --git a/style-guide-checker/go.mod b/tools/style-guide-checker/go.mod similarity index 100% rename from style-guide-checker/go.mod rename to tools/style-guide-checker/go.mod diff --git a/style-guide-checker/main.go b/tools/style-guide-checker/main.go similarity index 100% rename from style-guide-checker/main.go rename to tools/style-guide-checker/main.go diff --git a/style-guide-checker/main_test.go b/tools/style-guide-checker/main_test.go similarity index 100% rename from style-guide-checker/main_test.go rename to tools/style-guide-checker/main_test.go diff --git a/version-upgrade-gen/Dockerfile b/tools/version-upgrade-gen/Dockerfile similarity index 100% rename from version-upgrade-gen/Dockerfile rename to tools/version-upgrade-gen/Dockerfile diff --git a/version-upgrade-gen/README.md b/tools/version-upgrade-gen/README.md similarity index 100% rename from version-upgrade-gen/README.md rename to tools/version-upgrade-gen/README.md diff --git a/version-upgrade-gen/go.mod b/tools/version-upgrade-gen/go.mod similarity index 100% rename from version-upgrade-gen/go.mod rename to tools/version-upgrade-gen/go.mod diff --git a/version-upgrade-gen/main.go b/tools/version-upgrade-gen/main.go similarity index 100% rename from version-upgrade-gen/main.go rename to tools/version-upgrade-gen/main.go