Add Makefile and scripts to automate Foreman version addition

Makefile

@@ -0,0 +1,27 @@
+.PHONY: help foreman-download foreman-setup foreman-add-version cleanup
+
+help:
+	@echo "Foreman API Documentation Makefile"
+	@echo ""
+	@echo "Usage:"
+	@echo "  make foreman-add-version VERSION=X.Y    - Add a new Foreman version (complete workflow)"
+	@echo "  make foreman-download VERSION=X.Y        - Download apidoc artifact from GitHub Actions"
+	@echo "  make foreman-setup VERSION=X.Y           - Set up directory structure for new version"
+	@echo "  make cleanup                             - Run cleanup script"
+	@echo ""
+	@echo "Example:"
+	@echo "  make foreman-add-version VERSION=3.17"
+
+foreman-download:
+	@./scripts/foreman-download.sh $(VERSION)
+
+foreman-setup:
+	@./scripts/foreman-setup.sh $(VERSION)
+
+cleanup:
+	@./scripts/cleanup.sh
+
+foreman-add-version: foreman-download foreman-setup cleanup
+	@echo ""
+	@echo "Successfully added Foreman $(VERSION)!"
+	@echo "Please review the changes and commit them."

README.md

@@ -13,44 +13,56 @@ Follow these steps to add a new version:
 
 ### Foreman
 
-Fetch API docs for Foreman:
+To add a new Foreman version, use the following Makefile target:
 
-1. Go to https://github.com/theforeman/foreman/actions/workflows/foreman.yml?query=branch%3AX.Y-stable
-1. Pick the latest run of the action
-1. Download the `apidoc-*` artifact (there might be multiple, pick any one of them)
-
-You can also do this from the CLI using `gh`:
-```
-gh run download --repo theforeman/foreman --pattern 'apidoc-*' $(gh run list --repo theforeman/foreman --workflow foreman.yml --branch X.Y-stable --status completed --limit 1 --json databaseId --jq '.[].databaseId')
+```bash
+make foreman-add-version VERSION=X.Y
 ```
-Note: `gh` will automatically unzip the artifacts, so you only have to copy them.
 
-Prepare folder for the new version (X.Y)
+This will:
+1. Download the latest apidoc artifact from GitHub Actions for the X.Y-stable branch
+2. Set up the directory structure (foreman/X.Y)
+3. Update the `latest` symlink
+4. Copy apidoc files to the new version directory
+5. Update index.html with a link to the new version
+6. Run the cleanup script
+
+You can also run individual steps:
+```bash
+# Download only
+make foreman-download VERSION=X.Y
+
+# Setup only (after manual download)
+make foreman-setup VERSION=X.Y
 
-1. `cd foreman`
-1. `cp -r TEMPLATE X.Y`
-1. `ln -snf X.Y latest`
-1. `unzip -d X.Y/apidoc ~/Downloads/apidoc-<…>.zip`
-1. run cleanup script in the root of the apidocs repo: `cleanup.sh`
-1. update index.html file with a link to the new page
+# Run cleanup
+make cleanup
+```
+
+Or use the scripts directly:
+```bash
+./scripts/foreman-download.sh X.Y
+./scripts/foreman-setup.sh X.Y
+```
 
 ### Katello
 
-Generate API docs in a Foreman + Katello development environment:
+**Step 1: Generate API docs in a Foreman + Katello development environment**
 
 1. cd to the katello directory and checkout the relevant release branch
 1. cd to the foreman directory and checkout the relevant stable branch
 1. `APIPIE_RECORD=examples bundle exec rake test`
 1. `RAILS_ENV=production FOREMAN_APIPIE_LANGS=en bundle exec rake apipie:cache`
 
-Prepare folder for the new version (X.Y)
+**Step 2: Prepare folder for the new version (X.Y)**
+
+In the apidocs repository root:
 
-1. cd to the apidocs/katello directory
-1. `cp -r TEMPLATE X.Y`
-1. `ln -snf X.Y latest`
-1. `cp -r dir/to/foreman/public/apipie-cache/apidoc/* X.Y/apidoc`
-1. run cleanup script in apidocs repo: `cleanup.sh`
-1. update index.html file with a link to the new page
+1. `cp -r katello/TEMPLATE katello/X.Y`
+1. `ln -snf X.Y katello/latest`
+1. `cp -r /path/to/foreman/public/apipie-cache/apidoc/* katello/X.Y/apidoc`
+1. Update index.html with a link to the new version
+1. Run cleanup script: `./scripts/cleanup.sh`
 
 ## LICENSE
 

scripts/foreman-download.sh

@@ -0,0 +1,18 @@
+#!/bin/bash
+set -e
+
+VERSION="$1"
+
+if [ -z "$VERSION" ]; then
+    echo "ERROR: VERSION is required"
+    echo "Usage: $0 X.Y"
+    exit 1
+fi
+
+echo "Downloading apidoc artifact for Foreman $VERSION..."
+gh run download --repo theforeman/foreman --pattern 'apidoc-*' \
+    $(gh run list --repo theforeman/foreman --workflow foreman.yml \
+    --branch "${VERSION}-stable" --status completed --limit 1 \
+    --json databaseId --jq '.[].databaseId')
+
+echo "Download complete. Artifact saved to current directory."

scripts/foreman-setup.sh

@@ -0,0 +1,35 @@
+#!/bin/bash
+set -e
+
+VERSION="$1"
+
+if [ -z "$VERSION" ]; then
+    echo "ERROR: VERSION is required"
+    echo "Usage: $0 X.Y"
+    exit 1
+fi
+
+echo "Setting up Foreman $VERSION directory structure..."
+
+if [ -d "foreman/$VERSION" ]; then
+    echo "ERROR: foreman/$VERSION already exists"
+    exit 1
+fi
+
+cp -r foreman/TEMPLATE "foreman/$VERSION"
+ln -snf "$VERSION" foreman/latest
+
+echo "Copying apidoc files..."
+APIDOC_DIR=$(find . -maxdepth 1 -type d -name 'apidoc-*' | head -n 1)
+
+if [ -z "$APIDOC_DIR" ]; then
+    echo "ERROR: No apidoc-* directory found. Run foreman-download.sh first"
+    exit 1
+fi
+
+cp -r "$APIDOC_DIR"/* "foreman/$VERSION/apidoc/"
+
+echo "Updating index.html..."
+sed -i "|./foreman/latest/apidoc/v2.html\">latest</a></li>|a\\\t\t<li><a href=\"./foreman/$VERSION/apidoc/v2.html\">$VERSION</a></li>" index.html
+
+echo "Setup complete for Foreman $VERSION"