Use markdown-based docs for rocky10/almalinux10 x86_64 warewulf4 variants

Update docs.spec to build documentation from markdown sources for the two
variants that support the markdown approach (rocky10/x86_64/warewulf4/slurm
and almalinux10/x86_64/warewulf4/slurm). Other variants continue using LaTeX.

Changes:
- Add BuildRequires for markdown toolchain (pandoc, python3-jinja2,
  python3-pyyaml, mdtoc, texlive-xetex, etc.)
- Split build/install sections to handle markdown and LaTeX separately
- Add jinja2-render.py script as replacement for jinja2-cli (not available
  on RHEL 10)
- Update Makefile.common to use jinja2-render.py instead of jinja2

Generated with Claude Code (https://claude.ai/code)

Signed-off-by: Adrian Reber <areber@redhat.com>

Author: adrianreber

components/admin/docs/SPECS/docs.spec

@@ -11,6 +11,7 @@
 %include %{_sourcedir}/OHPC_macros
 
 %define recipe_base docs/recipes/install
+%define recipe_base_md docs/recipes/install/poc-markdown
 %define recipe_dest %{buildroot}/%{OHPC_PUB}/doc/recipes
 
 Name:           docs%{PROJ_DELIM}
@@ -25,6 +26,19 @@ Source0:        docs-ohpc.tar
 BuildRequires:  git
 BuildRequires:  make
 BuildRequires:  python3
+
+# Requirements for markdown-based documentation (pandoc + jinja2)
+BuildRequires:  pandoc
+BuildRequires:  python3-jinja2
+BuildRequires:  python3-pyyaml
+BuildRequires:  mdtoc%{PROJ_DELIM}
+BuildRequires:  texlive-xetex
+BuildRequires:  texlive-adjustbox
+BuildRequires:  texlive-collectbox
+BuildRequires:  texlive-unicode-math
+BuildRequires:  texlive-lm-math
+
+# Requirements for LaTeX-based documentation (and shared with markdown/pandoc)
 BuildRequires:  texlive-latex
 BuildRequires:  texlive-caption
 BuildRequires:  texlive-colortbl
@@ -75,14 +89,28 @@ from the OpenHPC software stack.
 %define parser_perl ../../../../parse_doc.pl
 %define parser_python ../../../../parse_doc.py
 
+# Build markdown-based documentation
+for recipe_path in \
+	"almalinux10/x86_64/warewulf4/slurm" \
+	"rocky10/x86_64/warewulf4/slurm" \
+; do
+	pushd "%{recipe_base_md}/${recipe_path}"
+
+	# Build markdown, PDF, and recipe.sh
+	make
+	make pdf
+	make recipe
+
+	popd
+done
+
+# Build LaTeX-based documentation
 for recipe_path in \
 	"almalinux10/x86_64/confluent/slurm" \
 	"almalinux10/x86_64/openchami/slurm" \
-	"almalinux10/x86_64/warewulf4/slurm" \
 	"almalinux10/aarch64/warewulf4/slurm" \
 	"openeuler24.03/x86_64/warewulf4/slurm" \
 	"openeuler24.03/aarch64/warewulf4/slurm" \
-	"rocky10/x86_64/warewulf4/slurm" \
 	"rocky10/aarch64/warewulf4/slurm" \
 	"rocky10/x86_64/openchami/slurm" \
 ; do
@@ -131,14 +159,22 @@ done
 install -m 0644 -p docs/ChangeLog %{buildroot}/%{OHPC_PUB}/doc/ChangeLog
 install -m 0644 -p docs/Release_Notes.txt %{buildroot}/%{OHPC_PUB}/doc/Release_Notes.txt
 
+# Install markdown-based documentation
+for recipe_path in \
+	"almalinux10/x86_64/warewulf4/slurm" \
+	"rocky10/x86_64/warewulf4/slurm" \
+; do
+	install -m 0644 -p -D "%{recipe_base_md}/${recipe_path}/steps.pdf" "%{recipe_dest}/${recipe_path}/Install_guide.pdf"
+	install -m 0755 -p -D "%{recipe_base_md}/${recipe_path}/recipe.sh" "%{recipe_dest}/${recipe_path}/recipe.sh"
+done
+
+# Install LaTeX-based documentation
 for recipe_path in \
 	"almalinux10/x86_64/confluent/slurm" \
 	"almalinux10/x86_64/openchami/slurm" \
-	"almalinux10/x86_64/warewulf4/slurm" \
 	"almalinux10/aarch64/warewulf4/slurm" \
 	"openeuler24.03/x86_64/warewulf4/slurm" \
 	"openeuler24.03/aarch64/warewulf4/slurm" \
-	"rocky10/x86_64/warewulf4/slurm" \
 	"rocky10/aarch64/warewulf4/slurm" \
 	"rocky10/x86_64/openchami/slurm" \
 ; do

docs/recipes/install/poc-markdown/common/Makefile.common

@@ -20,7 +20,7 @@ COMMON_TEMPLATES := ../../../../common
 HEADER_TEX := .header-includes.tex
 
 # jinja2 command with search path for includes
-JINJA2 := jinja2
+JINJA2 := $(COMMON_TEMPLATES)/jinja2-render.py
 JINJA2_FLAGS := --strict --format=yaml
 
 # Build the final markdown document

docs/recipes/install/poc-markdown/common/jinja2-render.py

@@ -0,0 +1,101 @@
+#!/usr/bin/env python3
+"""
+Simple Jinja2 template renderer - replacement for jinja2-cli.
+
+Usage: jinja2-render.py [--strict] [--format=yaml] TEMPLATE [DATA_FILE] [-o OUTPUT]
+
+This script provides a minimal replacement for the jinja2-cli tool,
+supporting the subset of features used by OpenHPC documentation builds.
+"""
+
+import argparse
+import os
+import sys
+from pathlib import Path
+
+import yaml
+from jinja2 import Environment, FileSystemLoader, StrictUndefined, Undefined
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Render Jinja2 templates with YAML data",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument(
+        "template",
+        help="Jinja2 template file to render",
+    )
+    parser.add_argument(
+        "data_file",
+        nargs="?",
+        help="YAML data file with template variables",
+    )
+    parser.add_argument(
+        "-o", "--output",
+        dest="output",
+        help="Output file (default: stdout)",
+    )
+    parser.add_argument(
+        "--strict",
+        action="store_true",
+        help="Fail on undefined variables",
+    )
+    parser.add_argument(
+        "--format",
+        dest="data_format",
+        default="yaml",
+        choices=["yaml"],
+        help="Data file format (default: yaml)",
+    )
+
+    args = parser.parse_args()
+
+    # Resolve template path
+    template_path = Path(args.template).resolve()
+    if not template_path.exists():
+        print(f"Error: Template file not found: {args.template}", file=sys.stderr)
+        sys.exit(1)
+
+    # Set up Jinja2 environment with template directory as search path
+    template_dir = template_path.parent
+    env = Environment(
+        loader=FileSystemLoader(str(template_dir)),
+        undefined=StrictUndefined if args.strict else Undefined,
+        # Keep trailing newlines (like jinja2-cli default)
+        keep_trailing_newline=True,
+    )
+
+    # Load template
+    template = env.get_template(template_path.name)
+
+    # Load data from YAML file
+    data = {}
+    if args.data_file:
+        data_path = Path(args.data_file)
+        if not data_path.exists():
+            print(f"Error: Data file not found: {args.data_file}", file=sys.stderr)
+            sys.exit(1)
+
+        with open(data_path, "r", encoding="utf-8") as f:
+            data = yaml.safe_load(f) or {}
+
+    # Render template
+    try:
+        output = template.render(**data)
+    except Exception as e:
+        print(f"Error rendering template: {e}", file=sys.stderr)
+        sys.exit(1)
+
+    # Write output
+    if args.output:
+        output_path = Path(args.output)
+        output_path.parent.mkdir(parents=True, exist_ok=True)
+        with open(output_path, "w", encoding="utf-8") as f:
+            f.write(output)
+    else:
+        sys.stdout.write(output)
+
+
+if __name__ == "__main__":
+    main()