Skip to content

Commit c5eef23

Browse files
caviricaviri
authored
Merge pull request #42 from sdsc-ordes/develop
release(docs): landing redesign + Docusaurus theming + nodes registry
2 parents 1bd3d7d + 48584ee commit c5eef23

18 files changed

Lines changed: 1849 additions & 650 deletions

File tree

‎.github/workflows/docs-pages-deploy.yml‎

Lines changed: 34 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,22 @@
11
name: docs-pages-deploy
22

3+
# Publishes the consolidated docs/ directory to GitHub Pages:
4+
# - docs/index.html the project landing
5+
# - docs/env-wizard/ the static infra/.env wizard
6+
# - docs/env-builder.html legacy env helper
7+
# - docs/assets, docs/statics landing assets
8+
# - docs/docs/ built Docusaurus site (this workflow
9+
# populates it from docs-site/)
10+
311
on:
412
push:
513
branches:
6-
- docs
14+
- main
715
paths:
16+
- "docs/**"
817
- "docs-site/**"
18+
- "nodes/**"
19+
- "scripts/build-nodes.mjs"
920
- ".github/workflows/docs-pages-deploy.yml"
1021
workflow_dispatch:
1122

@@ -24,12 +35,9 @@ env:
2435

2536
jobs:
2637
build:
27-
name: Build validated docs artifact
38+
name: Build consolidated docs artifact
2839
runs-on: ubuntu-latest
2940
timeout-minutes: 15
30-
defaults:
31-
run:
32-
working-directory: docs-site
3341
steps:
3442
- name: Checkout repository
3543
uses: actions/checkout@v5
@@ -47,20 +55,39 @@ jobs:
4755
cache-dependency-path: docs-site/pnpm-lock.yaml
4856

4957
- name: Install docs dependencies
58+
working-directory: docs-site
5059
run: pnpm install --frozen-lockfile
5160

52-
- name: Build docs
61+
- name: Regenerate hosted-nodes manifest from nodes/*.yaml
62+
# Zero-deps inline parser — see scripts/build-nodes.mjs.
63+
# Re-runs on every deploy so the landing reflects the latest
64+
# node definitions even if the PR author forgot to commit the
65+
# regenerated docs/data/nodes.json.
66+
run: node scripts/build-nodes.mjs
67+
68+
- name: Build Docusaurus
69+
working-directory: docs-site
5370
env:
5471
CI: "true"
72+
# Pages serves the repo at /open-pulse/, and the consolidated
73+
# tree puts Docusaurus output under docs/docs/, so the public
74+
# docs path is /open-pulse/docs/.
75+
DOCS_BASE_URL: "/open-pulse/docs/"
5576
run: pnpm build
5677

78+
- name: Stage Docusaurus build into docs/docs/
79+
run: |
80+
rm -rf docs/docs
81+
mkdir -p docs/docs
82+
cp -R docs-site/build/. docs/docs/
83+
5784
- name: Configure GitHub Pages
5885
uses: actions/configure-pages@v5
5986

6087
- name: Upload Pages artifact
6188
uses: actions/upload-pages-artifact@v3
6289
with:
63-
path: docs-site/build
90+
path: docs
6491

6592
deploy:
6693
name: Deploy to GitHub Pages

‎.gitignore‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,10 @@ infra/services/airflow/src/env_variables.json
2222
# can't pollute the working tree. Per-service subdirs under the configured
2323
# OPEN_PULSE_DATA_DIR are also covered by this single rule.
2424
data/
25+
# Whitelist the docs landing's data dir (hosts the generated nodes.json
26+
# and any other static JSON the landing fetches).
27+
!docs/data/
28+
!docs/data/**
2529
infra/services/graphdb/graphdb-data/
2630

2731
# Tentris local data and licenses
@@ -76,6 +80,10 @@ node_modules/
7680
docs-site/build/
7781
docs-site/.docusaurus/
7882
docs-site/.cache/
83+
docs-site/.pnpm-store/
84+
# Docusaurus build is staged here by docs-pages-deploy.yml at deploy time;
85+
# do not track the generated content.
86+
docs/docs/
7987

8088
# Backup files (timestamped .bak from sed -i / cp -a operations)
8189
*.bak

‎docs-site/docs/getting-started/index.md‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -57,10 +57,11 @@ Default credentials: `openpulse` / `replace-me`. OpenSearch (in the
5757

5858
### `.env` wizard
5959

60-
Don't want to hand-edit the file? The static wizard at
61-
[`/env-wizard/`](pathname:///env-wizard/) walks through the questions, generates
62-
strong tokens locally with the Web Crypto API (nothing leaves the
63-
browser), and outputs a complete `infra/.env` you can paste or download.
60+
Don't want to hand-edit the file? The static `.env` wizard linked from
61+
the [project landing](https://sdsc-ordes.github.io/open-pulse/) walks
62+
through the questions, generates strong tokens locally with the Web
63+
Crypto API (nothing leaves the browser), and outputs a complete
64+
`infra/.env` you can paste or download.
6465

6566
## Hack on the package
6667

‎docs-site/docs/operations/index.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,5 +10,6 @@ Use this section for operational procedures, branch responsibilities, and releas
1010
Start with:
1111

1212
- [Branch model](./branch-model.md)
13+
- [Register a hosted node](./register-a-node.md)
1314
- [Migration from static docs landing](./migration-from-static-docs.md)
1415
- [Release checklist](./release-checklist.md)

‎docs-site/docs/operations/register-a-node.md‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
---
2+
title: Register a hosted node
3+
---
4+
5+
# Register a hosted node
6+
7+
Open Pulse can be self-hosted. To make your instance discoverable from
8+
the project landing page, drop a YAML descriptor under `nodes/`. CI
9+
regenerates `docs/data/nodes.json` and the landing automatically
10+
renders your card on next deploy.
11+
12+
## Quick path — node builder
13+
14+
A static, browser-only form at
15+
[`/node-builder/`](https://sdsc-ordes.github.io/open-pulse/node-builder/)
16+
walks through the schema, previews the YAML live, and opens GitHub's
17+
"new file" editor with the YAML pre-filled — no clone needed.
18+
19+
Workflow:
20+
21+
1. Open the [node builder](https://sdsc-ordes.github.io/open-pulse/node-builder/).
22+
2. Fill in the form (name, URL, institution, …). The right-hand pane
23+
shows the YAML you'd commit.
24+
3. Click **Open PR on GitHub** → lands you in the file editor at
25+
`github.com/sdsc-ordes/open-pulse/new/main/nodes/<slug>.yaml`.
26+
4. Review, commit, open the PR. Maintainers merge it; the next
27+
docs-pages-deploy publishes your card.
28+
29+
## Manual path
30+
31+
If you'd rather work from a clone:
32+
33+
```bash
34+
cp nodes/epfl.yaml nodes/<your-slug>.yaml
35+
$EDITOR nodes/<your-slug>.yaml
36+
node scripts/build-nodes.mjs # regenerates docs/data/nodes.json
37+
```
38+
39+
Open a PR with the new YAML (and the regenerated JSON, though CI will
40+
also re-run the script before deploy).
41+
42+
## Schema
43+
44+
See [`nodes/README.md`](https://github.com/sdsc-ordes/open-pulse/blob/main/nodes/README.md)
45+
for the field-by-field reference.
46+
47+
| Field | Required | Example |
48+
| --- | --- | --- |
49+
| `name` | yes | `EPFL` |
50+
| `institution` | yes | `EPFL Open Science` |
51+
| `location` | yes | `Lausanne, Switzerland` |
52+
| `flag` | no | `🇨🇭` |
53+
| `url` | yes | `https://openpulse.epfl.ch` |
54+
| `status` | yes | `live` / `beta` / `coming-soon` |
55+
| `description` | yes | One- or two-sentence pitch. Multi-line block scalars are supported. |
56+
| `contact` | no | Email or handle of the maintainer. |

‎docs-site/docusaurus.config.js‎

Lines changed: 41 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,21 @@
11
// @ts-check
22

3+
// Env-driven baseUrl so the same config works locally (default "/docs/")
4+
// and on GitHub Pages where the site lives under /open-pulse/docs/.
5+
const baseUrl = process.env.DOCS_BASE_URL || "/docs/";
6+
// The landing lives one level above the docs (consolidated under docs/).
7+
const landingHref = baseUrl.replace(/\/docs\/$/, "/");
8+
39
/** @type {import('@docusaurus/types').Config} */
410
const config = {
511
title: "Open Pulse Docs",
6-
tagline: "Documentation source of truth",
12+
tagline: "Open-source ecosystem monitoring — documentation",
713

8-
url: "https://example.com",
9-
baseUrl: "/",
14+
url: "https://sdsc-ordes.github.io",
15+
baseUrl,
1016

11-
organizationName: "open-pulse",
12-
projectName: "open-pulse-1",
17+
organizationName: "sdsc-ordes",
18+
projectName: "open-pulse",
1319

1420
onBrokenLinks: "throw",
1521
markdown: {
@@ -18,6 +24,25 @@ const config = {
1824
}
1925
},
2026

27+
// Match the landing's typography (Manrope + JetBrains Mono).
28+
headTags: [
29+
{
30+
tagName: "link",
31+
attributes: { rel: "preconnect", href: "https://fonts.googleapis.com" }
32+
},
33+
{
34+
tagName: "link",
35+
attributes: { rel: "preconnect", href: "https://fonts.gstatic.com", crossorigin: "true" }
36+
},
37+
{
38+
tagName: "link",
39+
attributes: {
40+
rel: "stylesheet",
41+
href: "https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@400;500&family=Manrope:wght@400;500;600;700&display=swap"
42+
}
43+
}
44+
],
45+
2146
i18n: {
2247
defaultLocale: "en",
2348
locales: ["en"]
@@ -48,7 +73,17 @@ const config = {
4873
title: "Open Pulse Docs",
4974
items: [
5075
{ to: "/getting-started", label: "Getting Started", position: "left" },
51-
{ to: "/operations/branch-model", label: "Branch Model", position: "left" }
76+
{ to: "/operations/branch-model", label: "Branch Model", position: "left" },
77+
{
78+
href: landingHref,
79+
label: "← Open Pulse",
80+
position: "right"
81+
},
82+
{
83+
href: "https://github.com/sdsc-ordes/open-pulse",
84+
label: "GitHub",
85+
position: "right"
86+
}
5287
]
5388
}
5489
})

0 commit comments

Comments
 (0)