Skip to content

Commit 765d46a

Browse files
erlendellefsenerlendellefsen
authored
feat(docs): migrate to mkdocs material with generated API reference (#129)
1 parent e501631 commit 765d46a

30 files changed

Lines changed: 212 additions & 174 deletions

‎.config/dotnet-tools.json‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,13 @@
88
"csharpier"
99
],
1010
"rollForward": false
11+
},
12+
"intility.mkdocsdotnetapi": {
13+
"version": "0.1.4",
14+
"commands": [
15+
"mkdocs-dotnet-api"
16+
],
17+
"rollForward": false
1118
}
1219
}
1320
}

‎.github/release-please-config.json‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,8 @@
2222
"type": "xml",
2323
"path": "JsonApiToolkit/JsonApiToolkit.csproj",
2424
"xpath": "//Project/PropertyGroup/Version"
25-
}
25+
},
26+
"mkdocs.yaml"
2627
]
2728
}
2829
}

‎.github/workflows/build-docs.yml‎

Lines changed: 0 additions & 58 deletions
This file was deleted.

‎.github/workflows/ci-cd.yml‎

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,14 +2,14 @@ name: CI/CD Pipeline
22

33
on:
44
pull_request:
5-
branches: [main]
5+
branches: [ main ]
66
paths-ignore:
77
- "docs/**"
88
- "**.md"
99
- ".github/ISSUE_TEMPLATE/**"
1010
- ".claude/**"
1111
release:
12-
types: [published]
12+
types: [ published ]
1313

1414
concurrency:
1515
group: ${{ github.workflow }}-${{ github.ref }}
@@ -29,6 +29,9 @@ jobs:
2929
uses: actions/setup-dotnet@c2fa09f4bde5ebb9d1777cf28262a3eb3db3ced7 # v5
3030
with:
3131
dotnet-version: 10.0.x
32+
source-url: https://nuget.pkg.github.com/Intility/index.json
33+
env:
34+
NUGET_AUTH_TOKEN: ${{ secrets.NUGET_AUTH_TOKEN }}
3235

3336
- name: Restore
3437
run: dotnet restore --locked-mode
@@ -66,4 +69,5 @@ jobs:
6669
run: dotnet pack JsonApiToolkit/JsonApiToolkit.csproj -c Release --no-restore
6770

6871
- name: Publish to GitHub Packages
69-
run: dotnet nuget push "JsonApiToolkit/bin/Release/*.nupkg" --api-key ${{ secrets.NUGET_AUTH_TOKEN }}
72+
run: dotnet nuget push "JsonApiToolkit/bin/Release/*.nupkg" --api-key ${{
73+
secrets.NUGET_AUTH_TOKEN }}

‎.github/workflows/docs.yml‎

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
name: "Docs: Check & Deploy"
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
paths:
8+
- "docs/**"
9+
- "mkdocs.yaml"
10+
- "JsonApiToolkit/**"
11+
- ".github/workflows/docs.yml"
12+
pull_request:
13+
workflow_dispatch:
14+
15+
permissions:
16+
contents: read
17+
packages: read
18+
pages: write
19+
id-token: write
20+
21+
concurrency:
22+
group: pages-${{ github.event_name == 'pull_request' && github.head_ref || 'deploy' }}
23+
cancel-in-progress: true
24+
25+
jobs:
26+
changes:
27+
name: Detect changes
28+
if: github.event_name == 'pull_request'
29+
runs-on: ubuntu-latest
30+
permissions:
31+
contents: read
32+
pull-requests: read
33+
outputs:
34+
docs: ${{ steps.filter.outputs.docs }}
35+
steps:
36+
- uses: dorny/paths-filter@fbd0ab8f3e69293af611ebaee6363fc25e6d187d # v4.0.1
37+
id: filter
38+
with:
39+
filters: |
40+
docs:
41+
- 'docs/**'
42+
- 'mkdocs.yaml'
43+
- 'CHANGELOG.md'
44+
- 'JsonApiToolkit/**'
45+
- '.github/workflows/docs.yml'
46+
47+
build:
48+
name: "Docs: Build"
49+
needs: changes
50+
if: always() && (needs.changes.result == 'skipped' || needs.changes.outputs.docs == 'true')
51+
runs-on: ubuntu-latest
52+
steps:
53+
- uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
54+
with:
55+
fetch-depth: 0
56+
57+
- uses: actions/setup-dotnet@c2fa09f4bde5ebb9d1777cf28262a3eb3db3ced7 # v5
58+
with:
59+
dotnet-version: 10.0.x
60+
source-url: https://nuget.pkg.github.com/Intility/index.json
61+
env:
62+
NUGET_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
63+
64+
- uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
65+
with:
66+
python-version: "3.13"
67+
68+
- name: Build library (for API XML docs)
69+
env:
70+
NUGET_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
71+
run: dotnet build JsonApiToolkit/JsonApiToolkit.csproj -c Release -o JsonApiToolkit/bin/docs
72+
73+
- name: Restore .NET tools
74+
env:
75+
NUGET_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
76+
run: dotnet tool restore
77+
78+
- name: Generate API reference
79+
run: dotnet tool run mkdocs-dotnet-api -- --input JsonApiToolkit/bin/docs --output docs/api --strict
80+
81+
- name: Install Python dependencies
82+
run: uv venv && uv pip install -r docs/requirements.txt
83+
84+
- name: Build Documentation
85+
run: uv run mkdocs build --strict
86+
87+
- name: Upload artifact
88+
if: github.event_name != 'pull_request'
89+
uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
90+
with:
91+
path: "site"
92+
93+
deploy:
94+
name: Deploy
95+
if: always() && needs.build.result == 'success' && github.event_name != 'pull_request'
96+
runs-on: ubuntu-latest
97+
needs: build
98+
environment:
99+
name: github-pages
100+
url: ${{ steps.deployment.outputs.page_url }}
101+
steps:
102+
- name: Deploy to GitHub Pages
103+
id: deployment
104+
uses: actions/deploy-pages@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128 # v5.0.0

‎.gitignore‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -407,9 +407,10 @@ obj
407407
core_*
408408
docs/markdown-cheat-sheet.md
409409

410-
# DocFX
411-
_site
412-
api
410+
# MkDocs
411+
/site/
412+
.venv/
413+
/docs/api/
413414

414415
# Claude
415416
.claude

‎README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
[![CI/CD Pipeline](https://github.com/intility/Intility.JsonApiToolkit/actions/workflows/ci-cd.yml/badge.svg)](https://github.com/intility/Intility.JsonApiToolkit/actions/workflows/ci-cd.yml)
2-
[![Build Docs](https://github.com/intility/Intility.JsonApiToolkit/actions/workflows/build-docs.yml/badge.svg)](https://github.com/intility/Intility.JsonApiToolkit/actions/workflows/build-docs.yml)
2+
[![Docs](https://github.com/intility/Intility.JsonApiToolkit/actions/workflows/docs.yml/badge.svg)](https://github.com/intility/Intility.JsonApiToolkit/actions/workflows/docs.yml)
33

44
# Intility.JsonApiToolkit
55

‎docs/.pages‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
nav:
2+
- Home:
3+
- Welcome: index.md
4+
- introduction.md
5+
- getting-started.md
6+
- Guides:
7+
- querying.md
8+
- build-query.md
9+
- enhanced-error-handling.md
10+
- performance.md
11+
- security.md
12+
- api-controller-examples.md
13+
- debugging.md
14+
- upgrade-guide.md
15+
- integrations
16+
- api
17+
- contributing.md

docs/docs/api-controller-examples.md renamed to docs/api-controller-examples.md

File renamed without changes.

docs/docs/build-query.md renamed to docs/build-query.md

File renamed without changes.

0 commit comments

Comments
 (0)