Skip to content

Commit cf58af4

Browse files
koenbeukkoenbeuk
authored
Merge pull request #194 from EFNext/feature/docs-website
Docs website
2 parents 8a07cb1 + 8615ec7 commit cf58af4

36 files changed

Lines changed: 7135 additions & 1000 deletions

‎.github/copilot-instructions.md‎

Lines changed: 59 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -10,13 +10,15 @@
1010
src/
1111
EntityFrameworkCore.Projectables.Abstractions/ # [Projectable] attribute, enums
1212
EntityFrameworkCore.Projectables.Generator/ # Roslyn IIncrementalGenerator
13+
EntityFrameworkCore.Projectables.CodeFixes/ # Roslyn code fix providers (EFP0001/0002/0008/0012)
1314
EntityFrameworkCore.Projectables/ # Runtime library (EF Core integration)
1415
tests/
15-
EntityFrameworkCore.Projectables.Generator.Tests/ # Roslyn generator unit tests (Verify snapshots)
16-
EntityFrameworkCore.Projectables.FunctionalTests/ # End-to-end EF Core tests (Verify snapshots)
17-
EntityFrameworkCore.Projectables.Tests/ # Misc unit tests
18-
benchmarks/ # BenchmarkDotNet benchmarks
19-
samples/ # Readme sample project
16+
EntityFrameworkCore.Projectables.Generator.Tests/ # Roslyn generator unit tests (Verify snapshots)
17+
EntityFrameworkCore.Projectables.CodeFixes.Tests/ # Code fix unit tests (Verify snapshots)
18+
EntityFrameworkCore.Projectables.FunctionalTests/ # End-to-end EF Core tests (Verify snapshots)
19+
EntityFrameworkCore.Projectables.Tests/ # Misc unit tests
20+
benchmarks/ # BenchmarkDotNet benchmarks
21+
samples/ # Readme sample project
2022
```
2123

2224
---
@@ -233,7 +235,7 @@ $env:VERIFY_AUTO_APPROVE = "true"; dotnet test
233235
| `ProjectableDescriptor.cs` | Pure data record describing a projectable member |
234236
| `ProjectableAttributeData.cs` | Serializable snapshot of `[Projectable]` attribute values (no live Roslyn objects) |
235237
| `ProjectionRegistryEmitter.cs` | Emits `ProjectionRegistry.g.cs` |
236-
| `Diagnostics.cs` | All `DiagnosticDescriptor` constants (EFP0001–EFP0009) |
238+
| `Diagnostics.cs` | All `DiagnosticDescriptor` constants (EFP0001–EFP0012) |
237239

238240
### Incremental generator rules
239241
- **Never capture live Roslyn objects** (`ISymbol`, `SemanticModel`, `Compilation`, `AttributeData`) in the incremental pipeline transforms — they break caching. Use `ProjectableAttributeData` (a plain struct) instead.
@@ -243,15 +245,20 @@ $env:VERIFY_AUTO_APPROVE = "true"; dotnet test
243245

244246
## Diagnostics Reference
245247

246-
| ID | Severity | Title |
247-
|---------|----------|----------------------------------------------------|
248-
| EFP0001 | Warning | Block-bodied member support is experimental |
249-
| EFP0002 | Error | Null-conditional expression unsupported |
250-
| EFP0003 | Warning | Unsupported statement in block-bodied method |
251-
| EFP0004 | Error | Statement with side effects in block-bodied method |
252-
| EFP0005 | Warning | Potential side effect in block-bodied method |
253-
| EFP0006 | Error | Method/property should expose a body definition |
254-
| EFP0007 | Warning | Non-projectable method call in block body |
248+
| ID | Severity | Title | Code Fix |
249+
|---------|----------|----------------------------------------------------------------|-----------------------------------------------------------|
250+
| EFP0001 | Warning | Block-bodied member support is experimental | Add `AllowBlockBody = true` to `[Projectable]` |
251+
| EFP0002 | Error | Null-conditional expression not configured | Configure `NullConditionalRewriteSupport` |
252+
| EFP0003 | Warning | Unsupported statement in block-bodied method | — |
253+
| EFP0004 | Error | Statement with side effects in block-bodied method | — |
254+
| EFP0005 | Warning | Potential side effect in block-bodied method | — |
255+
| EFP0006 | Error | Method or property should expose a body definition | — |
256+
| EFP0007 | Error | Unsupported pattern in projectable expression | — |
257+
| EFP0008 | Error | Target class is missing a parameterless constructor | Add parameterless constructor to the class |
258+
| EFP0009 | Error | Delegated constructor cannot be analyzed for projection | — |
259+
| EFP0010 | Error | UseMemberBody target member not found | — |
260+
| EFP0011 | Error | UseMemberBody target member is incompatible | — |
261+
| EFP0012 | Info | [Projectable] factory method can be converted to a constructor | Convert to `[Projectable]` constructor (+ update callers) |
255262

256263
---
257264

@@ -280,6 +287,43 @@ $env:VERIFY_AUTO_APPROVE = "true"; dotnet test
280287

281288
---
282289

290+
## Documentation & README
291+
292+
### When to update `README.md`
293+
294+
- A user-facing feature is added, changed, or removed — keep the **feature table** current
295+
- Supported EF Core / .NET versions change
296+
- NuGet package names or the "Getting started" steps change
297+
298+
### When to update `docs/`
299+
300+
The docs site is a **VitePress** project (`docs/`). Run it locally with:
301+
302+
```bash
303+
cd docs
304+
npm install # first time only
305+
npm run dev
306+
```
307+
308+
Update the relevant page(s) in `docs/` whenever:
309+
310+
- A feature's behavior changes — edit the corresponding guide or reference page
311+
- A new doc page is added or an existing one is removed — **also update the sidebar** in `docs/.vitepress/config.mts`
312+
- Package installation or `UseProjectables()` API changes — update `docs/guide/quickstart.md`
313+
314+
### Doc structure
315+
316+
| Folder | Content |
317+
|-------------------|------------------------------------------------------|
318+
| `docs/guide/` | Getting-started guides (quickstart, core concepts) |
319+
| `docs/reference/` | Attribute reference, diagnostics, compatibility mode |
320+
| `docs/advanced/` | Internals, block-bodied members, limitations |
321+
| `docs/recipes/` | End-to-end usage examples |
322+
323+
The VitePress sidebar is declared in `docs/.vitepress/config.mts` — keep it in sync with actual files.
324+
325+
---
326+
283327
## Package Management
284328

285329
Central package version management is enabled (`ManagePackageVersionsCentrally = true`).

‎.github/workflows/docs.yml‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
name: Deploy Docs to GitHub Pages
2+
3+
on:
4+
push:
5+
branches:
6+
- master
7+
# TODO: Remove this when the docs website is ready to be merged into master :
8+
- feature/docs-website
9+
paths:
10+
- 'docs/**'
11+
- '.github/workflows/docs.yml'
12+
workflow_dispatch:
13+
14+
# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
15+
permissions:
16+
contents: write
17+
18+
# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
19+
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
20+
concurrency:
21+
group: pages
22+
cancel-in-progress: false
23+
24+
jobs:
25+
deploy:
26+
name: Build and deploy VitePress site
27+
runs-on: ubuntu-latest
28+
steps:
29+
- name: Checkout
30+
uses: actions/checkout@v4
31+
with:
32+
fetch-depth: 0 # Needed for lastUpdated feature
33+
34+
- name: Setup Node.js
35+
uses: actions/setup-node@v4
36+
with:
37+
node-version: 22
38+
cache: npm
39+
cache-dependency-path: docs/package-lock.json
40+
41+
- name: Install dependencies
42+
working-directory: docs
43+
run: npm ci
44+
45+
- name: Build VitePress site
46+
working-directory: docs
47+
run: npm run build
48+
49+
- name: Deploy to GitHub Pages
50+
uses: peaceiris/actions-gh-pages@v4
51+
with:
52+
deploy_key: ${{ secrets.ACTIONS_DEPLOY_KEY }}
53+
publish_dir: ./docs/.vitepress/dist
54+
external_repository: EFNext/efnext.github.io
55+
publish_branch: main
56+
user_name: 'github-actions[bot]'
57+
user_email: 'github-actions[bot]@users.noreply.github.com'
58+

‎.gitignore‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -366,3 +366,7 @@ FodyWeavers.xsd
366366
*.received.*
367367

368368
.idea
369+
370+
# Docs
371+
/docs/.vitepress/cache/
372+
/docs/.vitepress/dist/

‎EntityFrameworkCore.Projectables.sln‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -51,6 +51,7 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "workflows", "workflows", "{
5151
ProjectSection(SolutionItems) = preProject
5252
.github\workflows\build.yml = .github\workflows\build.yml
5353
.github\workflows\release.yml = .github\workflows\release.yml
54+
.github\workflows\docs.yml = .github\workflows\docs.yml
5455
EndProjectSection
5556
EndProject
5657
Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "EntityFrameworkCore.Projectables.CodeFixes", "src\EntityFrameworkCore.Projectables.CodeFixes\EntityFrameworkCore.Projectables.CodeFixes.csproj", "{1890C6AF-37A4-40B0-BD0C-7FB18357891A}"

0 commit comments

Comments
 (0)