Skip to content

Commit 5e9690f

Browse files
pchalametpchalamet
committed
feat(website): add docs site and tag-based pages publishing
1 parent b97ae0b commit 5e9690f

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

61 files changed

+21449
-2
lines changed

‎.github/scripts/release.sh‎

Lines changed: 16 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -160,7 +160,22 @@ fi
160160

161161
cp "$updated_changelog" CHANGELOG.md
162162

163-
git add CHANGELOG.md
163+
if [[ -d website ]]; then
164+
if ! command -v npm >/dev/null 2>&1; then
165+
echo "ERROR: npm is required to version/build website docs during release."
166+
exit 1
167+
fi
168+
169+
echo "Preparing website docs version ${version}..."
170+
(
171+
cd website
172+
npm ci
173+
npm run version-docs -- "${version}"
174+
npm run build
175+
)
176+
fi
177+
178+
git add CHANGELOG.md website
164179
git commit -m "chore(release): ${version}"
165180
git tag -a "${version}" -m "Release ${version}"
166181

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

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,19 @@ jobs:
4040
- name: Test
4141
run: dotnet test FScript.sln --configuration Release --no-build --logger "trx" --results-directory TestResults
4242

43+
- name: Setup Node.js
44+
uses: actions/setup-node@v4
45+
with:
46+
node-version: '22'
47+
cache: npm
48+
cache-dependency-path: website/package-lock.json
49+
50+
- name: Build website
51+
run: |
52+
cd website
53+
npm ci
54+
npm run build
55+
4356
- name: Upload test results
4457
if: always()
4558
uses: actions/upload-artifact@v4

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

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -44,6 +44,19 @@ jobs:
4444
- name: Test
4545
run: dotnet test FScript.sln --configuration Release --no-build --logger "trx" --results-directory TestResults
4646

47+
- name: Setup Node.js
48+
uses: actions/setup-node@v4
49+
with:
50+
node-version: '22'
51+
cache: npm
52+
cache-dependency-path: website/package-lock.json
53+
54+
- name: Build website
55+
run: |
56+
cd website
57+
npm ci
58+
npm run build
59+
4760
- name: Upload test results
4861
if: always()
4962
uses: actions/upload-artifact@v4

‎.github/workflows/deploy-website-on-tag.yml‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
name: 🌐 Deploy Website
2+
run-name: Deploy docs for ${{ github.ref_name }}
3+
4+
on:
5+
push:
6+
tags:
7+
- '*.*.*'
8+
workflow_dispatch:
9+
10+
permissions:
11+
contents: read
12+
pages: write
13+
id-token: write
14+
15+
concurrency:
16+
group: github-pages
17+
cancel-in-progress: true
18+
19+
jobs:
20+
deploy:
21+
runs-on: ubuntu-latest
22+
environment:
23+
name: github-pages
24+
url: ${{ steps.deployment.outputs.page_url }}
25+
steps:
26+
- name: Checkout
27+
uses: actions/checkout@v4
28+
29+
- name: Setup Node.js
30+
uses: actions/setup-node@v4
31+
with:
32+
node-version: '22'
33+
cache: npm
34+
cache-dependency-path: website/package-lock.json
35+
36+
- name: Install website dependencies
37+
run: |
38+
cd website
39+
npm ci
40+
41+
- name: Build website
42+
run: |
43+
cd website
44+
npm run build
45+
46+
- name: Configure GitHub Pages
47+
uses: actions/configure-pages@v5
48+
49+
- name: Upload Pages artifact
50+
uses: actions/upload-pages-artifact@v4
51+
with:
52+
path: website/build
53+
54+
- name: Deploy to GitHub Pages
55+
id: deployment
56+
uses: actions/deploy-pages@v4

‎CHANGELOG.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,9 @@ All notable changes to FScript are documented in this file.
66

77
- Added a new `MagnusOpera.FScript.TypeProvider` package that type-checks scripts at compile time and exposes exported functions as strongly-typed F# members with runtime signature compatibility checks.
88
- Stabilized type-provider integration tests in CI by hardening spawned `dotnet` process handling and adding job-level CI timeouts to prevent long hangs.
9+
- Added a Docusaurus-based documentation website under `website/` focused on FScript language learning, examples, and embedding guidance.
10+
- Added tag-triggered GitHub Pages deployment and release-time docs version snapshotting for the website.
11+
- Expanded website content with didactic language chapters, embedded runnable examples, detailed stdlib reference, VS Code/Open VSX setup, and practical embedding/type-provider guides.
912

1013
## [0.59.0]
1114

‎Makefile‎

Lines changed: 16 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
.PHONY: build test smoke-tests verify-changelog release-prepare clean publish publish-darwin publish-linux publish-windows pack-nuget publish-all
1+
.PHONY: build test smoke-tests verify-changelog release-prepare clean publish publish-darwin publish-linux publish-windows pack-nuget publish-all website-install website-build website-serve website-version website-typecheck
22

33
build:
44
dotnet build FScript.sln -c Release
@@ -47,3 +47,18 @@ pack-nuget:
4747
dotnet pack -c $(config) -p:Version=$(version) -o $(PWD)/.out src/FScript.Runtime
4848

4949
publish-all: build test publish publish-darwin publish-linux publish-windows pack-nuget
50+
51+
website-install:
52+
cd website && npm ci
53+
54+
website-build:
55+
cd website && npm run build
56+
57+
website-serve:
58+
cd website && npm run serve
59+
60+
website-version:
61+
cd website && npm run version-docs -- $(version)
62+
63+
website-typecheck:
64+
cd website && npm run typecheck

‎README.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -168,12 +168,22 @@ See [`docs/specs/sandbox-and-security.md`](docs/specs/sandbox-and-security.md) f
168168

169169
## Documentation
170170

171+
- Documentation website: `https://magnusopera.github.io/FScript/`
171172
- Documentation portal: [`docs/README.md`](docs/README.md)
172173
- Tutorial: [`docs/guides/getting-started-tutorial.md`](docs/guides/getting-started-tutorial.md)
173174
- Specifications index: [`docs/specs/README.md`](docs/specs/README.md)
174175
- Architecture index: [`docs/architecture/README.md`](docs/architecture/README.md)
175176
- FScript vs F# / OCaml: [`docs/guides/fsharp-ocaml-differences.md`](docs/guides/fsharp-ocaml-differences.md)
176177

178+
Website development commands:
179+
180+
```bash
181+
make website-install
182+
make website-build
183+
make website-serve
184+
make website-version version=X.Y.Z
185+
```
186+
177187
## Changelog
178188

179189
- [`CHANGELOG.md`](CHANGELOG.md)

‎website/.gitignore‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Dependencies
2+
/node_modules
3+
4+
# Production
5+
/build
6+
7+
# Generated files
8+
.docusaurus
9+
.cache-loader
10+
11+
# Misc
12+
.DS_Store
13+
.env.local
14+
.env.development.local
15+
.env.test.local
16+
.env.production.local
17+
18+
npm-debug.log*
19+
yarn-debug.log*
20+
yarn-error.log*

‎website/README.md‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
# FScript Website
2+
3+
This folder contains the Docusaurus-powered FScript documentation website.
4+
5+
## Commands
6+
7+
```bash
8+
npm ci
9+
npm run start
10+
npm run build
11+
npm run serve
12+
npm run typecheck
13+
```
14+
15+
Create a new versioned docs snapshot:
16+
17+
```bash
18+
npm run version-docs -- X.Y.Z
19+
```
20+
21+
## Publishing
22+
23+
- GitHub Actions deploys this site to GitHub Pages on release tag pushes.
24+
- Docs versions are created during `make release-prepare version=X.Y.Z`.

‎website/docs/embedding/overview.md‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
---
2+
id: embedding-overview
3+
title: Embedding Overview
4+
slug: /embedding/overview
5+
---
6+
7+
FScript is designed for host applications that embed a scripting language safely.
8+
9+
## Embedding workflow
10+
11+
1. Reference language/runtime packages.
12+
2. Build a host context.
13+
3. Register extern functions your scripts can call.
14+
4. Load scripts (with include resolution if needed).
15+
5. Resolve exported function signatures.
16+
6. Execute exported functions and handle results/errors.
17+
18+
## NuGet packages
19+
20+
- [`MagnusOpera.FScript.Language`](https://www.nuget.org/packages/MagnusOpera.FScript.Language)
21+
- [`MagnusOpera.FScript.Runtime`](https://www.nuget.org/packages/MagnusOpera.FScript.Runtime)
22+
- [`MagnusOpera.FScript.TypeProvider`](https://www.nuget.org/packages/MagnusOpera.FScript.TypeProvider)
23+
24+
## Recommended reading order
25+
26+
1. [Real-World Embedding (Load, Resolve Type, Execute)](./real-world-embedding)
27+
2. [F# Type Provider and Use Cases](./type-provider)
28+
3. [Register Extern Functions](./register-externs)
29+
4. [Resolver and Includes](./resolver-and-includes)
30+
5. [Sandbox and Safety](./sandbox-and-safety)

0 commit comments

Comments
 (0)