Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .dockerignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
node_modules
dist
.astro
.cache
.git
4 changes: 4 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,11 @@ jobs:
- run: npm ci
- run: npm run typecheck
- run: npm test
- run: npm run icons
- run: npm run build
env:
# The foot of the site reads the people and the funding of the organisation from GitHub (tools/project.ts).
GITHUB_TOKEN: ${{ github.token }}
- uses: actions/upload-artifact@v4
with:
name: site
Expand Down
5 changes: 4 additions & 1 deletion .github/workflows/pages.yml
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ on:
# Every day, so a change in the documentation of a product that did not notify this repository still reaches the site.
schedule:
- cron: '23 5 * * *'
# A product repository tells this one when its docs/ changes (see the plan, docs-notify).
# A product repository tells this one when its docs/ changes (the reusable workflow docs-notify of didactika/.github).
repository_dispatch:
types: [docs-changed]
workflow_dispatch:
Expand Down Expand Up @@ -38,6 +38,9 @@ jobs:
- run: npm ci
- run: npm test
- run: npm run build
env:
# The foot of the site reads the people and the funding of the organisation from GitHub (tools/project.ts).
GITHUB_TOKEN: ${{ github.token }}
- uses: actions/upload-pages-artifact@v3
with:
path: dist
Expand Down
6 changes: 6 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -7,3 +7,9 @@ dist/
/src/content/docs/*/plugins/
/src/content/docs/*/packages/
/src/data/products.generated.json
/src/data/project.generated.json

# What the previews of a developer need; see compose.yaml.
/preview.refs.json
/public/docs-assets/
/public/product-icons/
38 changes: 38 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -54,6 +54,26 @@ Node 22.23 or later is required. To try the site with clones you already have, w
DOCS_SOURCES=/path/to/clones DOCS_NO_FETCH=1 npm run build
```

## Seeing it while you work

```bash
docker compose up # then open http://localhost:4321/
docker compose logs -f site
docker compose down
```

The site runs in a container with the development server of Astro. The products are read from clones on your machine (the folder above this repository by default, or `DOCS_SOURCES_DIR`), not from GitHub, so what you have committed locally shows up before it is pushed. The documentation is read again every few seconds and the page reloads by itself.

To see branches that are not merged yet, copy `preview.refs.example.json` to `preview.refs.json` and list there, for each product, the branch to read for each line. Anything the synchronisation finds wrong in the documentation is in the log.

## Writing a page

A page is `docs/<language>/<path>.md` in the repository of the product, with a front matter of `title`, `summary` and `order`. A value with a colon must be in quotes (`summary: "Two things: a and b"`); the build says which page breaks it.

- **Alerts:** write the ones of GitHub (`> [!NOTE]`, `> [!TIP]`, `> [!IMPORTANT]`, `> [!WARNING]`, `> [!CAUTION]`). They read well on GitHub and become asides on the site.
- **Links to other pages of the product:** `[text](page:guides/install)` or `[text](page:guides/install#step-2)`. The link stays in the version and language the reader is in.
- **Hide a page** a later version inherits: a file at the same path with `hidden: true` and a `reason`.

## Adding a product

1. In its repository, add `docs/docs.json` on `main`, and the pages under `docs/en/` and `docs/es/`.
Expand All @@ -63,3 +83,21 @@ DOCS_SOURCES=/path/to/clones DOCS_NO_FETCH=1 npm run build
## Licence

GPL-3.0-or-later, as Moodle.

## Technical documentation

The technical documentation of a product (domain model, requirements, use cases, analysis, design, code map) lives in `docs/<language>/technical/` of its repository. The portal shows it as the "Technical documentation" section of the product: the `README.md` of a folder is its index, the diagrams (`.svg`) and tables (`.csv`) next to a page are published with it, and links between files keep working. The colours of the diagrams are `rup/didactika.theme.json`; copy it into the `theme` key of the `rup.config.json` of the product.

## Publishing

The site is built and deployed by `.github/workflows/pages.yml` to <https://docs.didactika.org/> on every push to `main`, every day, and when a product repository sends the event `docs-changed`. A product repository sends it with the reusable workflow `docs-notify` of `didactika/.github`, which needs the organisation secret `DOCS_DISPATCH_TOKEN` (a fine-grained token with "Contents: read and write" on this repository).

Turning it on once, by an administrator:

```bash
gh repo edit didactika/docs --visibility public --accept-visibility-change-consequences
gh api -X POST repos/didactika/docs/pages -f build_type=workflow
gh api -X PUT repos/didactika/docs/pages -f cname=docs.didactika.org -F https_enforced=true
```

and a `CNAME` record `docs` that points to `didactika.github.io` in the DNS of didactika.org.
62 changes: 58 additions & 4 deletions astro.config.ts
Original file line number Diff line number Diff line change
@@ -1,6 +1,8 @@
import {existsSync, readFileSync} from 'node:fs';
import {join} from 'node:path';
import {defineConfig} from 'astro/config';
import starlight from '@astrojs/starlight';
import type {StarlightUserConfig} from '@astrojs/starlight/types';

interface Language {
code: string;
Expand All @@ -13,6 +15,7 @@ interface Product {
slug: string;
kind: 'plugin' | 'package';
title: Record<string, string>;
lines: Array<{id: string; label: string; latest: boolean; sections: string[]; pageIds: string[]}>;
}

const json = <T>(path: string, fallback: T): T => (existsSync(path) ? (JSON.parse(readFileSync(path, 'utf8')) as T) : fallback);
Expand All @@ -25,12 +28,32 @@ const locales = Object.fromEntries(languages.map((language) => [language.code, {
const products = json<{products: Product[]}>('./src/data/products.generated.json', {products: []}).products;
const translated = (texts: Record<string, string>) => Object.fromEntries(languages.map((language) => [language.code, texts[language.code] ?? texts.en]));

// A text of the interface in each language (src/i18n/<language>.json); what a language lacks is taken from English.
const dictionaries = Object.fromEntries(languages.map((language) => [language.code, json<Record<string, string>>(join('./src/i18n', `${language.code}.json`), {})]));
const uiText = (key: string, fallback: string): Record<string, string> => Object.fromEntries(languages.map((language) => [language.code, dictionaries[language.code][key] ?? dictionaries.en?.[key] ?? fallback]));
const titleCase = (name: string): string => name.replace(/-/g, ' ').replace(/^./, (first) => first.toUpperCase());

const kinds = [
{kind: 'plugin', label: 'Plugins', es: 'Plugins', dir: 'plugins'},
{kind: 'package', label: 'Packages', es: 'Paquetes', dir: 'packages'},
] as const;

const sidebar = kinds
/**
* The technical documentation of a product, in the order of the method (RUP): what the product models, what it must do, how it is analysed and
* designed, and where it lives in the code. The folders come from the tool that writes the model, which names them in its own way, so the
* order is set here and the names come from the dictionaries.
*/
const DISCIPLINES = ['domain', 'requirements', 'analysis', 'design', 'implementation'];
const technicalItems = (directory: string, pageIds: string[]) => [
{label: uiText('overview', 'Overview').en, translations: uiText('overview', 'Overview'), slug: directory},
...DISCIPLINES.filter((discipline) => pageIds.some((id) => id.startsWith(`technical/${discipline}/`))).map((discipline) => ({
label: uiText(`tech.${discipline}`, titleCase(discipline)).en,
translations: uiText(`tech.${discipline}`, titleCase(discipline)),
items: [{autogenerate: {directory: `${directory}/${discipline}`}}],
})),
];

const sidebar: NonNullable<StarlightUserConfig['sidebar']> = kinds
.filter(({kind}) => products.some((product) => product.kind === kind))
.map(({kind, label, es, dir}) => ({
label,
Expand All @@ -41,23 +64,53 @@ const sidebar = kinds
label: product.title.en,
translations: translated(product.title),
collapsed: true,
items: [{autogenerate: {directory: `${dir}/${product.slug}`, collapsed: true}}],
// One group for each version, newest first, so the navigation stays in the version the reader is in.
items: [...product.lines].reverse().map((line) => ({
label: line.label,
collapsed: !line.latest,
items: [
{label: uiText('overview', 'Overview').en, translations: uiText('overview', 'Overview'), slug: `${dir}/${product.slug}/${line.id}`},
...line.sections.map((section) => ({
label: uiText(`section.${section}`, titleCase(section)).en,
translations: uiText(`section.${section}`, titleCase(section)),
// Only the section of the page the reader is on is open, so the whole map of the product fits in view.
collapsed: true,
items:
section === 'technical'
? technicalItems(`${dir}/${product.slug}/${line.id}/technical`, line.pageIds)
: [{autogenerate: {directory: `${dir}/${product.slug}/${line.id}/${section}`}}],
})),
],
})),
})),
}));

export default defineConfig({
site: 'https://docs.didactika.org',
trailingSlash: 'always',
build: {format: 'directory'},
// In Docker the files change on the other side of a mount, where the system does not tell the watcher; polling does the same job.
vite: {server: {watch: {usePolling: process.env.DOCS_POLL === '1'}}},
integrations: [
starlight({
title: {en: 'Didactika Docs', es: 'Documentación de Didactika'},
description: 'The documentation of the Moodle plugins and the npm packages of Didactika.',
description: 'Official documentation for the plugins and libraries of Didactika.',
defaultLocale: 'en',
locales,
logo: {src: './src/assets/didactika-logo.png', alt: 'Didactika'},
// The header, the title of a page, the navigation and the foot are drawn by the components of Didactika (src/components).
components: {
Header: './src/components/Header.astro',
PageTitle: './src/components/PageTitle.astro',
Sidebar: './src/components/Sidebar.astro',
Footer: './src/components/Footer.astro',
PageFrame: './src/components/PageFrame.astro',
},
favicon: '/brand/favicon.ico',
head: [
{
tag: 'script',
content: "(function(){var a=new URLSearchParams(location.search).get('mode');if(a==='dark'||a==='light'){try{localStorage.setItem('starlight-theme',a);}catch(e){}document.documentElement.dataset.theme=a;}})();",
},
{tag: 'link', attrs: {rel: 'icon', href: '/brand/favicon.svg', type: 'image/svg+xml'}},
{tag: 'link', attrs: {rel: 'icon', href: '/brand/favicon-32x32.png', sizes: '32x32', type: 'image/png'}},
{tag: 'link', attrs: {rel: 'icon', href: '/brand/favicon-16x16.png', sizes: '16x16', type: 'image/png'}},
Expand All @@ -66,6 +119,7 @@ export default defineConfig({
],
social: [{icon: 'github', label: 'GitHub', href: 'https://github.com/didactika'}],
customCss: ['./src/styles/didactika.css'],
pagination: false,
sidebar,
}),
],
Expand Down
36 changes: 36 additions & 0 deletions compose.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
# The site, served as it will be deployed: the portal of Didactika Docs with the documentation of the products that are in manifest.json.
#
# docker compose up -d then open http://localhost:4321/
# docker compose logs -f site to see the builds and what the synchronisation reports
# docker compose down to stop it
#
# The products are read from clones on this machine (DOCS_SOURCES_DIR, by default the folder above this repository), not from GitHub, so
# what you have committed locally shows up before it is pushed. To preview branches that are not merged, list them in preview.refs.json
# (copy preview.refs.example.json). The documentation is read again every few seconds and the site is built again when it changes, so what
# you see, search included, is what Pages publishes. `npm run dev` gives the development server instead, with hot reload and no search.
name: didactika-docs

services:
site:
image: node:22
working_dir: /app
ports:
- '4321:4321'
environment:
DOCS_SOURCES: /sources
DOCS_NO_FETCH: '1'
ASTRO_TELEMETRY_DISABLED: '1'
PORT: '4321'
# The clones belong to another user than the one in the container, and git refuses them unless it is told they are fine.
GIT_CONFIG_COUNT: '1'
GIT_CONFIG_KEY_0: safe.directory
GIT_CONFIG_VALUE_0: '*'
volumes:
- .:/app
# The dependencies are installed for Linux inside the container; the ones of this machine are not used.
- node_modules:/app/node_modules
- ${DOCS_SOURCES_DIR:-..}:/sources:ro
command: sh -c "npm ci --no-audit --no-fund && node tools/serve.ts"

volumes:
node_modules:
46 changes: 46 additions & 0 deletions package-lock.json

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

12 changes: 9 additions & 3 deletions package.json
Original file line number Diff line number Diff line change
Expand Up @@ -10,15 +10,21 @@
},
"scripts": {
"sync": "node tools/sync.ts",
"dev": "node tools/sync.ts && astro dev",
"build": "node tools/sync.ts && astro build",
"dev": "node tools/sync.ts && node tools/project.ts && astro dev",
"build": "node tools/sync.ts && node tools/project.ts && astro build",
"preview": "astro preview",
"serve": "node tools/serve.ts",
"brand": "node tools/build-brand.ts",
"test": "node --test \"tools/**/*.test.ts\"",
"typecheck": "astro sync && tsc --noEmit"
"typecheck": "astro sync && tsc --noEmit",
"icons": "node tools/check-icons.ts"
},
"dependencies": {
"@astrojs/starlight": "^0.42.10",
"@fontsource/ibm-plex-mono": "^5.3.0",
"@fontsource/ibm-plex-sans": "^5.3.0",
"@fontsource/space-grotesk": "^5.3.0",
"@iconify-json/material-symbols": "^1.2.98",
"astro": "^7.4.10",
"yaml": "^2.8.0"
},
Expand Down
6 changes: 6 additions & 0 deletions preview.refs.example.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
{
"didactika/moodle-local_delegateaccount": {
"main": "docs/portal-503",
"MOODLE_405_STABLE": "docs/portal-405"
}
}
Loading
Loading