From 784a3ffa021c69a07b48bd390373adbf1d89177a Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Wed, 10 Sep 2025 09:08:41 +0000 Subject: [PATCH 1/2] Initial plan From 36167e1d80a9cb4cfc92e8a04cab9e96db6a1303 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Wed, 10 Sep 2025 09:25:45 +0000 Subject: [PATCH 2/2] Add comprehensive GitHub Copilot instructions for docs-builder repository Co-authored-by: reakaleek <16325797+reakaleek@users.noreply.github.com> --- .github/copilot-instructions.md | 195 ++++++++++++++++++++++++++++++++ 1 file changed, 195 insertions(+) create mode 100644 .github/copilot-instructions.md diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 000000000..f68e85400 --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,195 @@ +# docs-builder + +**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.** + +Elastic's distributed documentation tooling system built on .NET 9, consisting of: +- **docs-builder**: CLI tool for building single documentation sets +- **docs-assembler**: CLI tool for assembling multiple doc sets +- Written in C# and F# with extensive Markdown processing capabilities + +## Working Effectively + +### Prerequisites and Setup +Install these in order: +```bash +# Install .NET 9.0 SDK +curl -sSL https://dot.net/v1/dotnet-install.sh | bash /dev/stdin --channel 9.0 +export PATH="$HOME/.dotnet:$PATH" + +# Restore .NET tools (required) +dotnet tool restore + +# Install Aspire workload (required for local development) +dotnet workload install aspire +``` + +### Build and Test Commands +```bash +# Basic build - takes 2 minutes. NEVER CANCEL. Set timeout to 180+ seconds. +dotnet build + +# Custom build system - takes 1.5 minutes. NEVER CANCEL. Set timeout to 120+ seconds. +./build.sh + +# Unit tests - takes 20 seconds. NEVER CANCEL. Set timeout to 60+ seconds. +./build.sh unit-test + +# Integration tests - takes 1 minute. NEVER CANCEL. Set timeout to 120+ seconds. +# Note: May fail in sandboxed environments due to network/service dependencies +./build.sh integrate + +# Clean build artifacts +./build.sh clean + +# Format code - takes 1 minute. NEVER CANCEL. Set timeout to 120+ seconds. +dotnet format + +# Lint/format check - takes 1 minute. NEVER CANCEL. Set timeout to 120+ seconds. +dotnet format --verify-no-changes +``` + +### Node.js Dependencies (Documentation Site) +```bash +cd src/Elastic.Documentation.Site + +# Install dependencies - takes 15 seconds +npm ci + +# Lint TypeScript/JavaScript - takes 2 seconds +npm run lint + +# Build web assets - takes 10 seconds +npm run build + +# Run tests +npm run test +``` + +### CLI Tools Usage +```bash +# Build documentation from ./docs folder - takes 15 seconds +dotnet run --project src/tooling/docs-builder + +# Serve with live reload at http://localhost:3000 +dotnet run --project src/tooling/docs-builder -- serve + +# Get help for docs-builder +dotnet run --project src/tooling/docs-builder -- --help + +# Get help for docs-assembler +dotnet run --project src/tooling/docs-assembler -- --help + +# Validate assembler configuration - takes 15 seconds +dotnet run --project src/tooling/docs-assembler -c release -- navigation validate +``` + +### Local Development Orchestration +```bash +# Run full local environment with Aspire (requires network access) +dotnet run --project aspire + +# With options for local development +dotnet run --project aspire -- --assume-cloned --skip-private-repositories + +# Watch mode for continuous development - monitors file changes +./build.sh watch +``` + +## Validation + +### Always run these before submitting changes: +```bash +# 1. Format code +dotnet format + +# 2. Build successfully +./build.sh + +# 3. Run unit tests +./build.sh unit-test + +# 4. Lint TypeScript/JavaScript +cd src/Elastic.Documentation.Site && npm run lint +``` + +### Testing Changes +- **ALWAYS** test the docs-builder CLI after making changes to verify functionality +- Test both building (`dotnet run --project src/tooling/docs-builder`) and serving (`dotnet run --project src/tooling/docs-builder -- serve`) +- For markdown processing changes, build the repository's own docs to validate +- For web components, build the npm assets and check output + +## Common Tasks + +### Key Project Structure +``` +src/ + ├── Elastic.Markdown/ # Core Markdown processing engine + ├── tooling/ + │ ├── docs-builder/ # Main CLI application + │ └── docs-assembler/ # Assembly tool + ├── Elastic.Documentation.Site/ # Web rendering components (TypeScript/CSS) + └── Elastic.Documentation.Configuration/ # Configuration handling + +tests/ + ├── Elastic.Markdown.Tests/ # C# unit tests + ├── authoring/ # F# authoring tests + └── docs-assembler.Tests/ # Assembler tests + +tests-integration/ # Integration tests +docs/ # Repository documentation +config/ # YAML configuration files +``` + +### Adding New Features +- **Markdown Extensions**: Add to `src/Elastic.Markdown/Myst/` +- **CLI Commands**: Extend `src/tooling/docs-builder/Cli/` or `docs-assembler/Cli/` +- **Web Components**: Add to `src/Elastic.Documentation.Site/` +- **Configuration**: Modify `src/Elastic.Documentation.Configuration/` + +### Important Files +- `build/Targets.fs` - F# build script definitions +- `docs-builder.sln` - Main solution file +- `global.json` - .NET SDK version (9.0.100) +- `Directory.Build.props` - MSBuild properties +- `Directory.Packages.props` - Centralized package management +- `dotnet-tools.json` - Required .NET tools + +### Build Timing Expectations +- **NEVER CANCEL** builds or tests - they may take longer than expected +- Initial build: ~2 minutes +- Incremental builds: ~30 seconds +- Unit tests: ~20 seconds +- Integration tests: ~1 minute (may fail without network access) +- Format checking: ~1 minute +- TypeScript build: ~10 seconds + +### Environment Notes +- Builds successfully on Ubuntu, macOS, and Windows +- Integration tests require network access (may fail in sandboxed environments) +- Uses both C# (.NET 9) and F# for different components +- TypeScript/Node.js for web asset building +- Self-hosting documentation demonstrating the tool's capabilities + +### Documentation Updates +When changing markdown syntax or rendering behavior, **always** update the documentation in the `/docs/` folder as this repository is self-documenting. + +## Quick Reference + +```bash +# Full development setup from fresh clone +curl -sSL https://dot.net/v1/dotnet-install.sh | bash /dev/stdin --channel 9.0 +export PATH="$HOME/.dotnet:$PATH" +dotnet tool restore +dotnet workload install aspire +cd src/Elastic.Documentation.Site && npm ci && cd ../.. + +# Build and validate changes +dotnet format +./build.sh +./build.sh unit-test +cd src/Elastic.Documentation.Site && npm run lint && npm run build + +# Test CLI functionality +dotnet run --project src/tooling/docs-builder +dotnet run --project src/tooling/docs-builder -- serve +``` \ No newline at end of file