added to docs data.

Author: RossBugginsNHS

docs/.gitignore

@@ -8,3 +8,4 @@ vendor
 node_modules
 _config.version.yml
 schemas
+_data/schema

docs/Makefile

@@ -2,14 +2,16 @@ BASE_URL ?= "/"
 VERSION ?= ""
 SCHEMA_PATTERN = *.schema.json
 SCHEMA_DOCS_PATTERN = *.md
+SCHEMA_YAML_DOCS_PATTERN= *.yaml
 SCHEMA_BASE_INPUT_DIR = ../schemas
-SCHEMA_INPUT_DIR = $(SCHEMA_BASE_INPUT_DIR)/output
-SCHEMA_DOCS_INPUT_DIR = $(SCHEMA_BASE_INPUT_DIR)/docs
+SCHEMA_INPUT_DIR = $(SCHEMA_BASE_INPUT_DIR)/output/schemas
+SCHEMA_DOCS_INPUT_DIR = $(SCHEMA_BASE_INPUT_DIR)/output/docs/md
+SCHEMA_YAML_DOCS_INPUT_DIR = $(SCHEMA_BASE_INPUT_DIR)/output/docs/yaml
 BASE_OUTPUT_DIR = _site
 BASE_DOCS_OUTPUT_DIR = schemas
 SCHEMA_OUTPUT_DIR = $(BASE_OUTPUT_DIR)/schemas
 SCHEMA_DOCS_OUTPUT_DIR = $(BASE_DOCS_OUTPUT_DIR)
-
+SCHEMA_YAML_DOCS_OUTPUT_DIR = _data/schema
 SHELL = /bin/bash
 
 default: install
@@ -29,7 +31,7 @@ define baseurlparam =
 $(if $(BASE_URL),-- --baseurl $(BASE_URL),-- --baseurl "")
 endef
 
-build: build-schemas copy-schema-docs build-docs copy-schemas show-build-output
+build: build-schemas copy-schema-docs copy-schema-yaml-docs build-docs copy-schemas show-build-output
 
 build-docs: version
 	npm run build $(baseurlparam)
@@ -48,6 +50,15 @@ copy-schema-docs:
 	@find $(SCHEMA_DOCS_OUTPUT_DIR) -type f -name "*" | sort
 
 
+copy-schema-yaml-docs:
+	mkdir -p $(SCHEMA_YAML_DOCS_OUTPUT_DIR)
+	@echo "Finding schema YAML docs files..."
+	@find $(SCHEMA_YAML_DOCS_INPUT_DIR) -name "$(SCHEMA_YAML_DOCS_PATTERN)" -print
+	@echo "Copying schema YAML docs files..."
+	rsync -av --include="*/" --include="$(SCHEMA_YAML_DOCS_PATTERN)" --exclude="*" $(SCHEMA_YAML_DOCS_INPUT_DIR)/ $(SCHEMA_YAML_DOCS_OUTPUT_DIR)/
+	@echo "Output in $(SCHEMA_YAML_DOCS_OUTPUT_DIR):"
+	@find $(SCHEMA_YAML_DOCS_OUTPUT_DIR) -type f -name "*" | sort
+
 copy-schemas:
 	mkdir -p $(SCHEMA_OUTPUT_DIR)
 	@echo "Finding schema files..."
@@ -69,6 +80,7 @@ clean-docs:
 clean-schemas:
 	rm -rf $(SCHEMA_OUTPUT_DIR)
 	rm -rf $(SCHEMA_DOCS_OUTPUT_DIR)
+	rm -rf $(SCHEMA_YAML_DOCS_OUTPUT_DIR)
 
 debug: version
 	npm run debug

docs/_config.yml

@@ -32,6 +32,7 @@ collections:
     output: true
     sort_by: order
 
+
 # Build settings
 theme: just-the-docs
 plugins:
@@ -86,6 +87,7 @@ callouts:
     color: blue
 
 
+
 defaults:
   - scope:
       path: "schemas"
@@ -98,6 +100,15 @@ defaults:
       owner: NHS Notify
       author: NHS Notify
       last_modified_date: 2025-01-01
+  - scope:
+      path: ""
+      type: "schema"
+    values:
+      layout: "page"
+      is_not_draft: false
+      owner: NHS Notify
+      author: NHS Notify
+      last_modified_date: 2025-01-01
 
 # Exclude from processing.
 # The following items will not be processed, by default.

docs/collections/_notify-repos/nhs-notify-repository-template.md

@@ -1,15 +1,19 @@
 # Variables
 SCHEMA_SRC_DIR := src
 OUTPUT_DIR := output
-DOCS_DIR := docs
+DOCS_OUTPUT_DIR := $(OUTPUT_DIR)/docs
+SCHEMAS_OUTPUT_DIR := $(OUTPUT_DIR)/schemas
 SCRIPTS_DIR := scripts
 YAML_TO_JSON_SCRIPT := $(SCRIPTS_DIR)/yaml_to_json.py
 GENERATE_DOCS_SCRIPT := $(SCRIPTS_DIR)/generate_docs.py
+GENERATE_DOCS_ALL_SCRIPT := $(SCRIPTS_DIR)/generate_docs_all.py
+GENERATE_DOCS_YAML_SCRIPT := $(SCRIPTS_DIR)/generate_docs_yaml.py
+GENERATE_DOCS_MD_SCRIPT := $(SCRIPTS_DIR)/generate_docs_markdown.py
 YAML_SCHEMAS := $(shell find $(SCHEMA_SRC_DIR) -name "*.schema.yaml" -type f)
 JSON_OUTPUTS := $(patsubst $(SCHEMA_SRC_DIR)/%.schema.yaml,$(OUTPUT_DIR)/%.schema.json,$(YAML_SCHEMAS))
 
 # Default target
-.PHONY: all clean build build-schemas convert-schemas config check-deps build-docs
+.PHONY: all clean build build-schemas convert-schemas config check-deps build-docs build-docs-yaml build-docs-md build-docs-legacy
 
 all: build
 
@@ -32,56 +36,87 @@ check-deps:
 	@python3 -c "import yaml" 2>/dev/null || \
 		(echo "PyYAML not found. Run 'make config' to install dependencies." && exit 1)
 
-# Convert all YAML schemas to JSON
+# Convert all YAML schemas to JSON (standalone - puts JSON files in schemas subdirectory)
 convert-schemas: check-deps $(OUTPUT_DIR)
 	@echo "Converting YAML schemas to JSON..."
+	@mkdir -p "$(SCHEMAS_OUTPUT_DIR)"
 	@for yaml_file in $(YAML_SCHEMAS); do \
 		relative_path=$${yaml_file#$(SCHEMA_SRC_DIR)/}; \
-		output_file="$(OUTPUT_DIR)/$${relative_path%.schema.yaml}.schema.json"; \
+		output_file="$(SCHEMAS_OUTPUT_DIR)/$${relative_path%.schema.yaml}.schema.json"; \
 		output_dir=$$(dirname "$$output_file"); \
 		mkdir -p "$$output_dir"; \
 		echo "Converting $$yaml_file to $$output_file"; \
 		python3 $(YAML_TO_JSON_SCRIPT) "$$yaml_file" "$$output_file"; \
 	done
 
-# Build all schemas
+# Build all schemas (standalone - just JSON conversion)
 build-schemas: convert-schemas
 	@echo "Building schemas complete!"
 	@echo "Found $(words $(YAML_SCHEMAS)) YAML schema(s):"
 	@for schema in $(YAML_SCHEMAS); do echo "  - $$schema"; done
-	@echo "Generated JSON schemas in $(OUTPUT_DIR)/"
+	@echo "Generated JSON schemas in $(SCHEMAS_OUTPUT_DIR)/"
 
 # Build everything (schemas and docs)
-build: build-schemas build-docs
-	@echo "Build complete! Generated JSON schemas and documentation."
+build: build-docs
+	@echo "Build complete! Generated JSON schemas and documentation in $(OUTPUT_DIR)/"
 
-# Generate documentation from schemas
+# Generate documentation from schemas (new two-stage approach)
+# This now includes JSON schema conversion as part of the documentation package
 build-docs: check-deps
-	@echo "Generating documentation from YAML schemas..."
-	@python3 $(GENERATE_DOCS_SCRIPT) $(SCHEMA_SRC_DIR) $(DOCS_DIR)
-	@echo "Documentation generated in $(DOCS_DIR)/"
+	@echo "Generating complete documentation package from YAML schemas..."
+	@python3 $(GENERATE_DOCS_ALL_SCRIPT) $(SCHEMA_SRC_DIR) $(OUTPUT_DIR)
+	@echo "Documentation package generated in $(OUTPUT_DIR)/"
+	@echo "  - JSON Schemas: $(SCHEMAS_OUTPUT_DIR)/"
+	@echo "  - YAML docs: $(DOCS_OUTPUT_DIR)/yaml/"
+	@echo "  - Markdown docs: $(DOCS_OUTPUT_DIR)/md/"
+
+# Generate only YAML documentation (for tool consumption)
+build-docs-yaml: check-deps
+	@echo "Generating YAML documentation from schemas..."
+	@python3 $(GENERATE_DOCS_YAML_SCRIPT) $(SCHEMA_SRC_DIR) $(DOCS_OUTPUT_DIR)/yaml
+	@echo "YAML documentation generated in $(DOCS_OUTPUT_DIR)/yaml/"
+
+# Generate only Markdown documentation (from existing YAML docs)
+build-docs-md: check-deps
+	@echo "Generating Markdown documentation from YAML docs..."
+	@test -d "$(DOCS_OUTPUT_DIR)/yaml" || (echo "Error: YAML docs not found. Run 'make build-docs-yaml' first." && exit 1)
+	@python3 $(GENERATE_DOCS_MD_SCRIPT) $(DOCS_OUTPUT_DIR)/yaml $(DOCS_OUTPUT_DIR)/md
+	@echo "Markdown documentation generated in $(DOCS_OUTPUT_DIR)/md/"
+
+# Generate documentation using legacy single-stage approach
+build-docs-legacy: check-deps
+	@echo "Generating documentation using legacy approach..."
+	@python3 $(GENERATE_DOCS_SCRIPT) $(SCHEMA_SRC_DIR) docs_legacy
+	@echo "Legacy documentation generated in docs_legacy/"
 
 # Clean output directory
 clean:
-	@echo "Cleaning output and docs directories..."
-	@rm -rf $(OUTPUT_DIR) $(DOCS_DIR)
+	@echo "Cleaning output directories..."
+	@rm -rf $(OUTPUT_DIR) docs_legacy
 	@echo "Clean complete!"
 
 # Show help
 help:
 	@echo "Available targets:"
-	@echo "  all           - Build everything (schemas + docs) (default)"
-	@echo "  build         - Build everything (schemas + docs)"
-	@echo "  build-schemas - Convert YAML schemas from src/ to JSON in output/ (preserving folder structure)"
-	@echo "  build-docs    - Generate Markdown documentation from YAML schemas"
-	@echo "  config        - Setup dependencies (Python, PyYAML)"
-	@echo "  list          - List all YAML schema files that would be processed"
-	@echo "  clean         - Remove output and docs directories"
-	@echo "  help          - Show this help message"
+	@echo "  all               - Build everything (complete documentation package) (default)"
+	@echo "  build             - Build everything (complete documentation package)"
+	@echo "  build-schemas     - Convert YAML schemas to JSON only (in output/schemas/)"
+	@echo "  build-docs        - Generate complete documentation package (JSON + YAML + Markdown docs)"
+	@echo "  build-docs-yaml   - Generate only YAML documentation (for tool consumption)"
+	@echo "  build-docs-md     - Generate only Markdown documentation (requires YAML docs)"
+	@echo "  build-docs-legacy - Generate documentation using legacy single-stage approach"
+	@echo "  config            - Setup dependencies (Python, PyYAML)"
+	@echo "  list              - List all YAML schema files that would be processed"
+	@echo "  clean             - Remove output directories"
+	@echo "  help              - Show this help message"
 	@echo ""
 	@echo "Source schemas are looked for in: $(SCHEMA_SRC_DIR)/"
-	@echo "Output JSON files are generated in: $(OUTPUT_DIR)/ (with preserved folder structure)"
-	@echo "Documentation files are generated in: $(DOCS_DIR)/ (with preserved folder structure)"
+	@echo "Output structure:"
+	@echo "  $(OUTPUT_DIR)/"
+	@echo "    ├── docs/"
+	@echo "    │   ├── yaml/     # YAML documentation files"
+	@echo "    │   └── md/       # Markdown documentation files"
+	@echo "    └── schemas/      # JSON schema files (converted from YAML)"
 
 # List all YAML schema files
 list: