|
| 1 | +# docs-builder |
| 2 | + |
| 3 | +**ALWAYS reference these instructions first and fallback to search or bash commands only when you encounter unexpected information that does not match the info here.** |
| 4 | + |
| 5 | +Elastic's distributed documentation tooling system built on .NET 9, consisting of: |
| 6 | +- **docs-builder**: CLI tool for building single documentation sets |
| 7 | +- **docs-assembler**: CLI tool for assembling multiple doc sets |
| 8 | +- Written in C# and F# with extensive Markdown processing capabilities |
| 9 | + |
| 10 | +## Working Effectively |
| 11 | + |
| 12 | +### Prerequisites and Setup |
| 13 | +Install these in order: |
| 14 | +```bash |
| 15 | +# Install .NET 9.0 SDK |
| 16 | +curl -sSL https://dot.net/v1/dotnet-install.sh | bash /dev/stdin --channel 9.0 |
| 17 | +export PATH="$HOME/.dotnet:$PATH" |
| 18 | + |
| 19 | +# Restore .NET tools (required) |
| 20 | +dotnet tool restore |
| 21 | + |
| 22 | +# Install Aspire workload (required for local development) |
| 23 | +dotnet workload install aspire |
| 24 | +``` |
| 25 | + |
| 26 | +### Build and Test Commands |
| 27 | +```bash |
| 28 | +# Basic build - takes 2 minutes. NEVER CANCEL. Set timeout to 180+ seconds. |
| 29 | +dotnet build |
| 30 | + |
| 31 | +# Custom build system - takes 1.5 minutes. NEVER CANCEL. Set timeout to 120+ seconds. |
| 32 | +./build.sh |
| 33 | + |
| 34 | +# Unit tests - takes 20 seconds. NEVER CANCEL. Set timeout to 60+ seconds. |
| 35 | +./build.sh unit-test |
| 36 | + |
| 37 | +# Integration tests - takes 1 minute. NEVER CANCEL. Set timeout to 120+ seconds. |
| 38 | +# Note: May fail in sandboxed environments due to network/service dependencies |
| 39 | +./build.sh integrate |
| 40 | + |
| 41 | +# Clean build artifacts |
| 42 | +./build.sh clean |
| 43 | + |
| 44 | +# Format code - takes 1 minute. NEVER CANCEL. Set timeout to 120+ seconds. |
| 45 | +dotnet format |
| 46 | + |
| 47 | +# Lint/format check - takes 1 minute. NEVER CANCEL. Set timeout to 120+ seconds. |
| 48 | +dotnet format --verify-no-changes |
| 49 | +``` |
| 50 | + |
| 51 | +### Node.js Dependencies (Documentation Site) |
| 52 | +```bash |
| 53 | +cd src/Elastic.Documentation.Site |
| 54 | + |
| 55 | +# Install dependencies - takes 15 seconds |
| 56 | +npm ci |
| 57 | + |
| 58 | +# Lint TypeScript/JavaScript - takes 2 seconds |
| 59 | +npm run lint |
| 60 | + |
| 61 | +# Build web assets - takes 10 seconds |
| 62 | +npm run build |
| 63 | + |
| 64 | +# Run tests |
| 65 | +npm run test |
| 66 | +``` |
| 67 | + |
| 68 | +### CLI Tools Usage |
| 69 | +```bash |
| 70 | +# Build documentation from ./docs folder - takes 15 seconds |
| 71 | +dotnet run --project src/tooling/docs-builder |
| 72 | + |
| 73 | +# Serve with live reload at http://localhost:3000 |
| 74 | +dotnet run --project src/tooling/docs-builder -- serve |
| 75 | + |
| 76 | +# Get help for docs-builder |
| 77 | +dotnet run --project src/tooling/docs-builder -- --help |
| 78 | + |
| 79 | +# Get help for docs-assembler |
| 80 | +dotnet run --project src/tooling/docs-assembler -- --help |
| 81 | + |
| 82 | +# Validate assembler configuration - takes 15 seconds |
| 83 | +dotnet run --project src/tooling/docs-assembler -c release -- navigation validate |
| 84 | +``` |
| 85 | + |
| 86 | +### Local Development Orchestration |
| 87 | +```bash |
| 88 | +# Run full local environment with Aspire (requires network access) |
| 89 | +dotnet run --project aspire |
| 90 | + |
| 91 | +# With options for local development |
| 92 | +dotnet run --project aspire -- --assume-cloned --skip-private-repositories |
| 93 | + |
| 94 | +# Watch mode for continuous development - monitors file changes |
| 95 | +./build.sh watch |
| 96 | +``` |
| 97 | + |
| 98 | +## Validation |
| 99 | + |
| 100 | +### Always run these before submitting changes: |
| 101 | +```bash |
| 102 | +# 1. Format code |
| 103 | +dotnet format |
| 104 | + |
| 105 | +# 2. Build successfully |
| 106 | +./build.sh |
| 107 | + |
| 108 | +# 3. Run unit tests |
| 109 | +./build.sh unit-test |
| 110 | + |
| 111 | +# 4. Lint TypeScript/JavaScript |
| 112 | +cd src/Elastic.Documentation.Site && npm run lint |
| 113 | +``` |
| 114 | + |
| 115 | +### Testing Changes |
| 116 | +- **ALWAYS** test the docs-builder CLI after making changes to verify functionality |
| 117 | +- Test both building (`dotnet run --project src/tooling/docs-builder`) and serving (`dotnet run --project src/tooling/docs-builder -- serve`) |
| 118 | +- For markdown processing changes, build the repository's own docs to validate |
| 119 | +- For web components, build the npm assets and check output |
| 120 | + |
| 121 | +## Common Tasks |
| 122 | + |
| 123 | +### Key Project Structure |
| 124 | +``` |
| 125 | +src/ |
| 126 | + ├── Elastic.Markdown/ # Core Markdown processing engine |
| 127 | + ├── tooling/ |
| 128 | + │ ├── docs-builder/ # Main CLI application |
| 129 | + │ └── docs-assembler/ # Assembly tool |
| 130 | + ├── Elastic.Documentation.Site/ # Web rendering components (TypeScript/CSS) |
| 131 | + └── Elastic.Documentation.Configuration/ # Configuration handling |
| 132 | +
|
| 133 | +tests/ |
| 134 | + ├── Elastic.Markdown.Tests/ # C# unit tests |
| 135 | + ├── authoring/ # F# authoring tests |
| 136 | + └── docs-assembler.Tests/ # Assembler tests |
| 137 | +
|
| 138 | +tests-integration/ # Integration tests |
| 139 | +docs/ # Repository documentation |
| 140 | +config/ # YAML configuration files |
| 141 | +``` |
| 142 | + |
| 143 | +### Adding New Features |
| 144 | +- **Markdown Extensions**: Add to `src/Elastic.Markdown/Myst/` |
| 145 | +- **CLI Commands**: Extend `src/tooling/docs-builder/Cli/` or `docs-assembler/Cli/` |
| 146 | +- **Web Components**: Add to `src/Elastic.Documentation.Site/` |
| 147 | +- **Configuration**: Modify `src/Elastic.Documentation.Configuration/` |
| 148 | + |
| 149 | +### Important Files |
| 150 | +- `build/Targets.fs` - F# build script definitions |
| 151 | +- `docs-builder.sln` - Main solution file |
| 152 | +- `global.json` - .NET SDK version (9.0.100) |
| 153 | +- `Directory.Build.props` - MSBuild properties |
| 154 | +- `Directory.Packages.props` - Centralized package management |
| 155 | +- `dotnet-tools.json` - Required .NET tools |
| 156 | + |
| 157 | +### Build Timing Expectations |
| 158 | +- **NEVER CANCEL** builds or tests - they may take longer than expected |
| 159 | +- Initial build: ~2 minutes |
| 160 | +- Incremental builds: ~30 seconds |
| 161 | +- Unit tests: ~20 seconds |
| 162 | +- Integration tests: ~1 minute (may fail without network access) |
| 163 | +- Format checking: ~1 minute |
| 164 | +- TypeScript build: ~10 seconds |
| 165 | + |
| 166 | +### Environment Notes |
| 167 | +- Builds successfully on Ubuntu, macOS, and Windows |
| 168 | +- Integration tests require network access (may fail in sandboxed environments) |
| 169 | +- Uses both C# (.NET 9) and F# for different components |
| 170 | +- TypeScript/Node.js for web asset building |
| 171 | +- Self-hosting documentation demonstrating the tool's capabilities |
| 172 | + |
| 173 | +### Documentation Updates |
| 174 | +When changing markdown syntax or rendering behavior, **always** update the documentation in the `/docs/` folder as this repository is self-documenting. |
| 175 | + |
| 176 | +## Quick Reference |
| 177 | + |
| 178 | +```bash |
| 179 | +# Full development setup from fresh clone |
| 180 | +curl -sSL https://dot.net/v1/dotnet-install.sh | bash /dev/stdin --channel 9.0 |
| 181 | +export PATH="$HOME/.dotnet:$PATH" |
| 182 | +dotnet tool restore |
| 183 | +dotnet workload install aspire |
| 184 | +cd src/Elastic.Documentation.Site && npm ci && cd ../.. |
| 185 | + |
| 186 | +# Build and validate changes |
| 187 | +dotnet format |
| 188 | +./build.sh |
| 189 | +./build.sh unit-test |
| 190 | +cd src/Elastic.Documentation.Site && npm run lint && npm run build |
| 191 | + |
| 192 | +# Test CLI functionality |
| 193 | +dotnet run --project src/tooling/docs-builder |
| 194 | +dotnet run --project src/tooling/docs-builder -- serve |
| 195 | +``` |
0 commit comments