|
| 1 | +# CLAUDE.md |
| 2 | + |
| 3 | +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 4 | + |
| 5 | +## Repository Purpose |
| 6 | + |
| 7 | +This repository contains the API reference documentation for Office Scripts. The documentation is **autogenerated** from TypeScript definition files and published to Microsoft Learn at https://learn.microsoft.com/javascript/api/office-scripts/overview. |
| 8 | + |
| 9 | +**CRITICAL**: Files in `/docs/docs-ref-autogen/` are autogenerated and should NEVER be edited directly. All changes to API documentation must be made to the source files in `/generate-docs/script-inputs/office-scripts-docs.d.ts`. |
| 10 | + |
| 11 | +## Documentation Generation Workflow |
| 12 | + |
| 13 | +### Build and Generate Documentation |
| 14 | + |
| 15 | +```bash |
| 16 | +cd generate-docs |
| 17 | +./GenerateDocs.sh |
| 18 | +``` |
| 19 | + |
| 20 | +This script: |
| 21 | +1. Cleans previous outputs (`node_modules`, `json`, `yaml` directories) |
| 22 | +2. Installs dependencies in both root and `scripts/` directory |
| 23 | +3. Runs preprocessor (`scripts/preprocessor.ts`) to: |
| 24 | + - Split `/generate-docs/script-inputs/office-scripts-docs.d.ts` into separate namespace files |
| 25 | + - Extract `ExcelScript` namespace → `api-extractor-inputs-excelscript/excelscript.d.ts` |
| 26 | + - Extract `OfficeScript` namespace → `api-extractor-inputs-officescript/officescript.d.ts` |
| 27 | + - Process samples from `/docs/sample-scripts/samples.yaml` into snippets |
| 28 | +4. Creates release versions by removing `@beta` APIs using `version-remover` |
| 29 | +5. Generates "what's new" reports comparing preview vs release APIs |
| 30 | +6. Runs `api-extractor` on all four input directories (preview and release for both namespaces) |
| 31 | +7. Runs **standard** `api-documenter` to generate YAML files (without custom Office flags) |
| 32 | +8. Runs postprocessor (`scripts/postprocessor.ts`) to: |
| 33 | + - **Load code snippets** from `json-preview/snippets.yaml` |
| 34 | + - Copy generated YAML to `/docs/docs-ref-autogen/` |
| 35 | + - **Insert examples** into YAML files by matching UIDs with snippets |
| 36 | + - Clean up YAML files (remove unsupported fields, fix formatting) |
| 37 | + - Generate and fix TOC (Table of Contents) with separate enum sections |
| 38 | + - **Track and warn about unused snippets** |
| 39 | +9. Runs `reference-coverage-tester` to validate API coverage |
| 40 | + |
| 41 | +### Architecture Overview |
| 42 | + |
| 43 | +**Input Files:** |
| 44 | +- `/generate-docs/script-inputs/office-scripts-docs.d.ts` - Combined source TypeScript definitions containing both `ExcelScript` and `OfficeScript` namespaces, separated by comment markers like `Begin ExcelScript namespace` |
| 45 | +- `/docs/sample-scripts/samples.yaml` - Code samples keyed by API signature (e.g., `'ExcelScript.Range#getValue:member(1)'`) |
| 46 | + |
| 47 | +**Processing Pipeline:** |
| 48 | +1. **Preprocessor** splits namespaces and processes samples |
| 49 | +2. **Version-remover** creates release versions (strips `@beta` tags) |
| 50 | +3. **API Extractor** generates JSON model files from `.d.ts` files |
| 51 | +4. **API Documenter** converts JSON to YAML documentation |
| 52 | +5. **Postprocessor** copies to final location, cleans up YAML, and fixes TOC structure |
| 53 | + |
| 54 | +**Output:** |
| 55 | +- `/docs/docs-ref-autogen/` - Final documentation files published to Microsoft Learn |
| 56 | + |
| 57 | +### Namespace Structure |
| 58 | + |
| 59 | +The combined input file (`office-scripts-docs.d.ts`) contains multiple namespaces separated by comment markers: |
| 60 | +```typescript |
| 61 | +//////////////////////////////////////////////////////////////// |
| 62 | +//////////////////// Begin ExcelScript namespace //////////////////// |
| 63 | +//////////////////////////////////////////////////////////////// |
| 64 | +// ExcelScript content here... |
| 65 | + |
| 66 | +//////////////////////////////////////////////////////////////// |
| 67 | +//////////////////// Begin OfficeScript namespace //////////////////// |
| 68 | +//////////////////////////////////////////////////////////////// |
| 69 | +// OfficeScript content here... |
| 70 | +``` |
| 71 | + |
| 72 | +Each namespace is extracted, processed independently, and generates separate documentation. |
| 73 | + |
| 74 | +## Adding or Editing Code Samples |
| 75 | + |
| 76 | +Samples are defined in `/docs/sample-scripts/samples.yaml` using this format: |
| 77 | + |
| 78 | +```yaml |
| 79 | +'ExcelScript.ClassName#methodName:member(1)': |
| 80 | + - |- |
| 81 | + /** |
| 82 | + * Description of what the sample does. |
| 83 | + */ |
| 84 | + function main(workbook: ExcelScript.Workbook) { |
| 85 | + // Sample code here |
| 86 | + } |
| 87 | +``` |
| 88 | +
|
| 89 | +The key format is: `'ExcelScript.'`*\<class-name\>*`#`*\<method-name\>*`:member(`*\<overload-number\>*`)` where overload-number is usually `1`. |
| 90 | + |
| 91 | +**Keep samples alphabetically sorted** by class and method name for maintainability. |
| 92 | + |
| 93 | +## Common Issues |
| 94 | + |
| 95 | +### Do Not Edit Autogenerated Files |
| 96 | + |
| 97 | +Never edit files in: |
| 98 | +- `/docs/docs-ref-autogen/` - Will be overwritten on next documentation generation |
| 99 | + |
| 100 | +To make documentation changes: |
| 101 | +1. Edit source at `/generate-docs/script-inputs/office-scripts-docs.d.ts` |
| 102 | +2. Run `./GenerateDocs.sh` to regenerate |
| 103 | + |
| 104 | +### Sample YAML Format |
| 105 | + |
| 106 | +Samples must: |
| 107 | +- Have a YAML key matching the API signature exactly |
| 108 | +- Start with ` - |-` on a new line after the key (preserves formatting) |
| 109 | +- Include a JSDoc comment explaining the sample |
| 110 | +- Be functional, readable, and targeted to the specific API |
| 111 | + |
| 112 | +## Migration from Office API Documenter (2025) |
| 113 | + |
| 114 | +Previously, this repository used a custom Office version of API Documenter (via the `--office` flag) to insert code examples and format API set links. This functionality has been **migrated to the postprocessor** for better maintainability: |
| 115 | + |
| 116 | +**What changed:** |
| 117 | +- Removed `--office` flag from `GenerateDocs.sh` (lines 56-57) |
| 118 | +- Added snippet loading and example insertion logic to `postprocessor.ts` |
| 119 | +- Examples are now inserted in priority order: |
| 120 | + 1. Append to `remarks` if it exists |
| 121 | + 2. Append to `syntax.return.description` if no remarks |
| 122 | + 3. Create new `remarks` if neither exists |
| 123 | +- API set link editing logic added (for future compatibility, though not currently used in Office Scripts) |
| 124 | + |
| 125 | +**Benefits:** |
| 126 | +- No longer dependent on custom Office fork of API Documenter |
| 127 | +- Easier to update API Documenter independently |
| 128 | +- All Office Scripts-specific customization in one place (postprocessor) |
| 129 | +- Better debugging (can inspect YAML before customization) |
| 130 | + |
| 131 | +## CI/CD |
| 132 | + |
| 133 | +GitHub Actions workflow (`.github/workflows/autogen-docs.yml`) automatically runs `GenerateDocs.sh` twice weekly (Tuesdays and Thursdays at 10:45 UTC) and creates a PR if documentation changes are detected. |
| 134 | + |
| 135 | +## Publishing |
| 136 | + |
| 137 | +Documentation is published via Microsoft's Open Publishing System (OPS) configured in `.openpublishing.publish.config.json`. The build uses DocFX v3 and includes custom TOC joining plugins. |
0 commit comments