Skip to content

Commit 9067e91

Browse files
Copilotreakaleek
Copilot
and
reakaleek
authored
Add comprehensive GitHub Copilot instructions for docs-builder repository (#1863)
* Initial plan * Add comprehensive GitHub Copilot instructions for docs-builder repository Co-authored-by: reakaleek <[email protected]> --------- Co-authored-by: copilot-swe-agent[bot] <[email protected]> Co-authored-by: reakaleek <[email protected]> Co-authored-by: Jan Calanog <[email protected]>
1 parent 10150f9 commit 9067e91

File tree

1 file changed

+195
-0
lines changed

1 file changed

+195
-0
lines changed

‎.github/copilot-instructions.md‎

Lines changed: 195 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,195 @@
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

Comments
 (0)