Skip to content

Commit fdbeab0

Browse files
draugangdraugang
committed
Added docs CD, beta
1 parent b6c427d commit fdbeab0

File tree

6 files changed

+204
-3
lines changed

6 files changed

+204
-3
lines changed

‎.github/PAGES.md‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
# GitHub Pages Configuration for ArchUnitTS Documentation
2+
3+
## Documentation Site
4+
5+
- **URL**: https://lukasniessen.github.io/ArchUnitTS/
6+
- **Source**: `docs/` folder generated by TypeDoc
7+
- **Updates**: Automatically on push to `main` branch
8+
9+
## TypeDoc Configuration
10+
11+
- **Config File**: `typedoc.json`
12+
- **Entry Point**: `index.ts`
13+
- **Output**: `docs/` folder
14+
- **Theme**: Default TypeDoc theme with navigation improvements
15+
16+
## GitHub Actions
17+
18+
- **Documentation Deployment**: `.github/workflows/docs.yaml`
19+
- **Integration Tests**: `.github/workflows/integrate.yaml`
20+
21+
## Local Development
22+
23+
```bash
24+
# Generate documentation
25+
npm run docs
26+
27+
# Watch mode (regenerates on file changes)
28+
npm run docs:watch
29+
30+
# Serve locally at http://localhost:3000
31+
npm run docs:serve
32+
```

‎.github/workflows/docs.yaml‎

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
name: Deploy Documentation
2+
3+
on:
4+
push:
5+
branches: [main]
6+
7+
# Allow one concurrent deployment
8+
concurrency:
9+
group: 'pages'
10+
cancel-in-progress: true
11+
12+
# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
13+
permissions:
14+
contents: read
15+
pages: write
16+
id-token: write
17+
18+
jobs:
19+
# Build job
20+
build:
21+
runs-on: ubuntu-latest
22+
steps:
23+
- name: Checkout
24+
uses: actions/checkout@v4
25+
with:
26+
fetch-depth: 0 # Needed for git revision info
27+
28+
- name: Setup Node.js
29+
uses: actions/setup-node@v4
30+
with:
31+
node-version: '20'
32+
cache: 'npm'
33+
34+
- name: Install dependencies
35+
run: npm ci
36+
37+
- name: Build project
38+
run: npm run build
39+
40+
## Note that we do not publish the library to npm ##
41+
## We only deploy the docs. We consider auto deploying the library ##
42+
## as too risky given the fact that there are no full time maintainers ##
43+
44+
- name: Generate documentation
45+
run: npm run docs
46+
47+
- name: Setup Pages
48+
uses: actions/configure-pages@v4
49+
50+
- name: Upload artifact
51+
uses: actions/upload-pages-artifact@v3
52+
with:
53+
path: './docs'
54+
55+
# Deployment job - only runs on main branch pushes
56+
deploy:
57+
if: github.ref == 'refs/heads/main' && github.event_name == 'push'
58+
environment:
59+
name: github-pages
60+
url: ${{ steps.deployment.outputs.page_url }}
61+
runs-on: ubuntu-latest
62+
needs: build
63+
steps:
64+
- name: Deploy to GitHub Pages
65+
id: deployment
66+
uses: actions/deploy-pages@v4

‎CONTRIBUTING.md‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,30 @@ Thanks for contributing!
1616
- PRs: Use feature branches, clear descriptions, ensure CI passes
1717
- Tests: Maintain high coverage
1818

19+
## Documentation
20+
21+
Documentation is automatically generated from TypeScript code using TypeDoc and deployed to GitHub Pages.
22+
23+
### Local Development
24+
25+
- Generate docs: `npm run docs`
26+
- Watch mode: `npm run docs:watch`
27+
- Serve locally: `npm run docs:serve`
28+
29+
### Writing Good Documentation
30+
31+
- Add JSDoc comments to all public APIs
32+
- Use `@example` tags for code examples
33+
- Use `@param` and `@returns` for functions
34+
- Use `@since` for version information
35+
- Group related functionality with `@group` tags
36+
37+
### Documentation Deployment
38+
39+
- Documentation is automatically deployed to [GitHub Pages](https://lukasniessen.github.io/ArchUnitTS/) on push to `main`
40+
- Documentation validation runs on all PRs
41+
- Configuration is in `typedoc.json`
42+
1943
## Issues
2044

2145
Bugs: Include environment, expected/actual behavior, steps, errors

‎README.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@ Enforce architecture rules in TypeScript and JavaScript projects. Check for depe
1919

2020
_Inspired by the amazing ArchUnit library but we are not affiliated with ArchUnit._
2121

22-
[Documentation](#readme) • [Use Cases](#-use-cases) • [Features](#-features) • [Contributing](CONTRIBUTING.md)
22+
[Documentation](https://lukasniessen.github.io/ArchUnitTS/) • [Use Cases](#-use-cases) • [Features](#-features) • [Contributing](CONTRIBUTING.md)
2323

2424
## ⚡ 5 min Quickstart
2525

@@ -982,6 +982,8 @@ How does ArchUnitTS work under the hood? See [here](info/TECHNICAL.md) for a dee
982982

983983
We highly appreciate contributions. We use GitHub Flow, meaning that we use feature branches, similar to GitFlow, but with proper CI and CD. As soon as something is merged or pushed to `main` it gets deployed. See more in [Contributing](CONTRIBUTING.md). See also our _'[Backlog](TODO.md)'_.
984984

985+
Note that _deploy_ here means updating the docs. We consider auto deploying the library to npm too risky given the fact that there are no full time maintainers.
986+
985987
## ℹ️ FAQ
986988

987989
**Q: What TypeScript/JavaScript testing frameworks are supported?**

‎package.json‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -55,7 +55,7 @@
5555
"bugs": {
5656
"url": "https://github.com/LukasNiessen/ArchUnitTS/issues"
5757
},
58-
"homepage": "https://github.com/LukasNiessen/ArchUnitTS#readme",
58+
"homepage": "https://lukasniessen.github.io/ArchUnitTS/",
5959
"license": "MIT",
6060
"engines": {
6161
"node": ">=14.0.0",
@@ -68,7 +68,9 @@
6868
"minorpub": "npm run clean && tsc && npm version minor && npm publish",
6969
"majorpub": "npm run clean && tsc && npm version major && npm publish",
7070
"build": "tsc",
71-
"docs": "typedoc --entryPointStrategy expand src",
71+
"docs": "typedoc --options typedoc.json",
72+
"docs:watch": "typedoc --options typedoc.json --watch",
73+
"docs:serve": "npm run docs && npx --yes serve docs",
7274
"format": "prettier --ignore-path .gitignore --write '**/*.ts*'",
7375
"format:check": "prettier --ignore-path .gitignore --check '**/*.ts*'",
7476
"test": "jest --no-cache",

‎typedoc.json‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
{
2+
"$schema": "https://typedoc.org/schema.json",
3+
"entryPoints": ["index.ts"],
4+
"entryPointStrategy": "expand",
5+
"out": "docs",
6+
"theme": "default",
7+
"name": "ArchUnitTS",
8+
"includeVersion": true,
9+
"readme": "README.md",
10+
"tsconfig": "tsconfig.json",
11+
"exclude": [
12+
"**/*.spec.ts",
13+
"**/*.test.ts",
14+
"**/test/**/*",
15+
"**/tests/**/*",
16+
"node_modules/**/*"
17+
],
18+
"excludeExternals": true,
19+
"excludeNotDocumented": false,
20+
"excludePrivate": true,
21+
"excludeProtected": false,
22+
"excludeInternal": true,
23+
"hideGenerator": false,
24+
"githubPages": true,
25+
"gitRevision": "main",
26+
"gitRemote": "origin",
27+
"categorizeByGroup": true,
28+
"categoryOrder": ["Files", "Metrics", "Slices", "Testing", "Common", "*"],
29+
"sort": ["source-order", "alphabetical"],
30+
"kindSortOrder": [
31+
"Project",
32+
"Module",
33+
"Namespace",
34+
"Enum",
35+
"EnumMember",
36+
"Class",
37+
"Interface",
38+
"TypeAlias",
39+
"Constructor",
40+
"Property",
41+
"Variable",
42+
"Function",
43+
"Accessor",
44+
"Method",
45+
"Parameter",
46+
"TypeParameter",
47+
"TypeLiteral",
48+
"CallSignature",
49+
"ConstructorSignature",
50+
"IndexSignature",
51+
"GetSignature",
52+
"SetSignature"
53+
],
54+
"searchInComments": true,
55+
"validation": {
56+
"notExported": true,
57+
"invalidLink": true,
58+
"notDocumented": false
59+
},
60+
"treatWarningsAsErrors": false,
61+
"preserveWatchOutput": false,
62+
"cleanOutputDir": true,
63+
"watch": false,
64+
"navigation": {
65+
"includeCategories": true,
66+
"includeGroups": true
67+
},
68+
"sitemapBaseUrl": "https://lukasniessen.github.io/ArchUnitTS/",
69+
"titleLink": "https://github.com/LukasNiessen/ArchUnitTS",
70+
"navigationLinks": {
71+
"GitHub": "https://github.com/LukasNiessen/ArchUnitTS",
72+
"NPM": "https://www.npmjs.com/package/archunit",
73+
"Examples": "https://github.com/LukasNiessen/ArchUnitTS/tree/main/examples"
74+
}
75+
}

0 commit comments

Comments
 (0)