# Mod Documentation Generator

This document covers `TODOS.phase-72.72.14.1.14`: generated mod API
documentation from the curated V2 mod API surface.

## Inputs And Output

The generator reads:

- `V2/ue/Content/V2/Modding/ModApiSurface_V2_Contract.json` for the capability
  list and policy allowlists.
- `V2/ue/Source/V2Modding/Private/V2ModLoading.cpp` for the source capability
  descriptors used by `BuildDefaultModApiCatalog`.

It writes:

- `V2/docs/modding/generated/mod-api-reference.md`

The generated reference includes every curated API capability, enum mapping,
source description, cosmetic mutation flag, policy notes, safety warnings, and
Lua examples for each capability.

## Command

Regenerate the reference:

```bash
python3 V2/ue/Tools/generate-v2-mod-api-docs.py
```

Check that the committed generated reference is current:

```bash
python3 V2/ue/Tools/generate-v2-mod-api-docs.py --check
```

The output is deterministic and does not include timestamps.

## Runtime Plan Surface

`BuildDefaultModDocumentationGeneratorPolicy` enables capability reference,
examples, policy notes, safety warnings, and deterministic output. Use
`BuildModApiDocumentationExample` to register example snippets and
`GenerateModApiDocumentationPlan` to validate the catalog, examples, source
contract path, and generated output path before running external tooling.

`GetGeneratedModApiDocumentationPath` returns the committed generated reference
path so editor tooling can link to the same artifact that CI checks.

## Verification

```bash
python3 V2/ue/Tools/check-v2-mod-documentation-generator.py
python3 V2/ue/Tools/generate-v2-mod-api-docs.py --check
python3 V2/ue/Tools/check-v2-mod-api-surface.py
python3 V2/ue/Tools/check-v2-mod-loading-system.py
python3 V2/ue/Tools/check-v2-ci-workflow.py
python3 V2/tools/validate-v2-docs.py
python3 -m py_compile V2/ue/Tools/check-v2-mod-documentation-generator.py V2/ue/Tools/generate-v2-mod-api-docs.py
python3 -m json.tool V2/ue/Content/V2/Modding/ModDocumentationGenerator_V2_Contract.json
```