Feature/materialSync

.prettierignore

@@ -29,4 +29,5 @@ static/katex/katex.min.css
 *.mp3
 *.jpeg
 *.jpg
-*.png
+*.png
+material.config.yaml

docusaurus.config.ts

@@ -5,6 +5,8 @@ import type {
   ShowEditThisPage,
   TdevConfig
 } from '@tdev/siteConfig/siteConfig';
+import type { VersionOptions } from '@docusaurus/plugin-content-docs';
+
 import { themes as prismThemes } from 'prism-react-renderer';
 import type { Config, OnBrokenMarkdownImagesFunction } from '@docusaurus/types';
 import type * as Preset from '@docusaurus/preset-classic';
@@ -98,6 +100,16 @@ const docusaurusConfig = withSiteConfig().then(async (siteConfig) => {
     loadedPlugins.push(excalidrawPluginConfig);
   }
 
+  const hasVersions = await fs.access(path.join(BUILD_LOCATION, 'versions.json')).then(() => true).catch(() => false);
+  const DEFAULT_VERSIONS: { [version: string]: VersionOptions } = {} ;
+  if (hasVersions) {
+    const docusaurusVersions = await fs.readFile(path.join(BUILD_LOCATION, 'versions.json'), 'utf-8').then((data) => JSON.parse(data) as string[]);
+    docusaurusVersions.forEach((version) => {
+      DEFAULT_VERSIONS[version] = { label: version, banner: 'none' };
+    });
+    DEFAULT_VERSIONS['current'] = { label: 'Material', banner: 'none' }
+  }
+
 
   const config: Config = applyTransformers(
     {
@@ -272,6 +284,7 @@ const docusaurusConfig = withSiteConfig().then(async (siteConfig) => {
                   beforeDefaultRemarkPlugins: BEFORE_DEFAULT_REMARK_PLUGINS,
                   ...DEFAULT_ADMONITION_CONFIG,
                   exclude: [...new Set([...GlobExcludeDefault, '**/node_modules/**'])],
+                  versions: Object.keys(DEFAULT_VERSIONS).length > 0 ? DEFAULT_VERSIONS : undefined,
                   ...(siteConfig.docs || {})
                 }
               : false,

material.config.yaml

@@ -0,0 +1,4 @@
+pages: []
+docs:
+  - from: packages/tdev/material-sync/README.mdx
+    to: tdev-website/docs/intro/03-class-management/index.mdx

package.json

@@ -9,7 +9,7 @@
     "scripts": {
         "docusaurus": "docusaurus",
         "start": "concurrently --raw --kill-others 'PACKAGE_SRC=packages PACKAGE_DEST=tdev-website/docs/packages docusaurus start' 'sleep 1s && ts-node --files updateSync/packageDocsSync/watch.ts --src packages --dest tdev-website/docs/packages'",
-        "prebuild": "ts-node --files updateSync/packageDocsSync/preBuild.ts --src packages --dest tdev-website/docs/packages",
+        "prebuild": "yarn workspace @tdev/material-sync sync && ts-node --files updateSync/packageDocsSync/preBuild.ts --src packages --dest tdev-website/docs/packages",
         "build": "docusaurus build",
         "swizzle": "docusaurus swizzle",
         "deploy": "docusaurus deploy",
@@ -21,7 +21,15 @@
         "format": "prettier --write .",
         "format:check": "prettier --check .",
         "test": "vitest --coverage",
-        "updateTdev": "ts-node --files updateSync/updateTdev.ts"
+        "updateTdev": "ts-node --files updateSync/updateTdev.ts",
+        "sync": "yarn workspace @tdev/material-sync sync",
+        "remove": "yarn workspace @tdev/material-sync run remove",
+        "postremove": "yarn workspace @tdev/material-sync sync",
+        "precleanup": "yarn workspace @tdev/material-sync restore",
+        "cleanup": "yarn workspace @tdev/material-sync cleanup",
+        "add": "yarn workspace @tdev/material-sync run add",
+        "addClass": "yarn workspace @tdev/material-sync run addClass",
+        "postadd": "yarn workspace @tdev/material-sync sync"
     },
     "dependencies": {
         "@docusaurus/core": "^3.10.1",
@@ -67,7 +75,7 @@
         "micromark-extension-math": "^3.1.0",
         "micromatch": "^4.0.8",
         "minimist": "^1.2.8",
-        "mobx": "^6.15.0",
+        "mobx": "^6.16.1",
         "mobx-react-lite": "^4.1.1",
         "mobx-utils": "^6.1.1",
         "qrcode.react": "^4.2.0",
@@ -111,7 +119,7 @@
         "remark-directive": "^4.0.0",
         "remark-frontmatter": "^5.0.0",
         "ts-node": "^10.9.2",
-        "typescript": "^6.0.2",
+        "typescript": "^6.0.3",
         "vfile": "^6.0.3",
         "vitest": "^2.0.5"
     },

packages/tdev/material-sync/README.mdx

@@ -0,0 +1,149 @@
+---
+page_id: 9a836e52-2ffc-47aa-9144-b3c247be6bbd
+---
+
+# Klassenmanagement
+
+Grundsätzlich werden jegliche Inhalte im Ordner `/docs` erstellt, abgelegt und mit git versioniert.
+
+Um den Klassen individuell zusammengestellte Inhalte zu präsentieren, wird im `material.config.yaml` festgelegt, welche Inhalte welcher Klasse angezeigt werden. Das Standard-Format sieht wie folgt aus:
+
+```yaml showLineNumbers
+28Gj:
+    - from: docs/OF-BYOD-Basics/
+      to: versioned_docs/version-28Gb/01-BYOD
+    - from: docs/OF-Word/
+      to: versioned_docs/version-28Gb/03-Word
+      ignore:
+          - _category_.yml
+29Ga:
+    - from: docs/OF-BYOD-Basics-29/
+      to: versioned_docs/version-29Ga/02-BYOD
+      open: true
+```
+
+`from`
+: Pfad zum Quellordner oder der Quelldatei, die verteilt werden soll. Der Pfad ist relativ zum Projektstammverzeichnis.
+`to`
+: Pfad zum Zielordner, in dem die Inhalte für die jeweilige Klasse abgelegt werden. Der Pfad ist relativ zum Projektstammverzeichnis.
+`ignore`
+: *optional*
+: Liste von Dateien oder Ordnern, die nicht kopiert werden sollen. Der Pfad ist relativ zum Quellordner.
+: ⚠️ aktuell können nur direkt im Quellordner liegende Dateien oder Ordner ignoriert werden. Unterordner werden nicht unterstützt.
+`open`
+: *optional*
+: Gibt an, ob der Ordner in der Navigation standardmässig geöffnet sein soll. In diesem Fall wird ein Datei `_category_.json` im Zielordner erstellt, in dem die Einstellung gespeichert wird.
+
+
+Obige Konfiguration kann auch abgekürzt wie folgt geschrieben werden:
+
+```yaml showLineNumbers
+28Gj:
+    - material: OF-BYOD-Basics
+      as: 01-BYOD
+    - material: OF-Word
+      as: 03-Word
+      ignore:
+          - _category_.yml
+29Ga:
+    - material: OF-BYOD-Basics-29
+      as: 02-BYOD
+      open: true
+```
+
+`material`
+: Pfad zum Quellordner, relativ zum Ordner `/docs`. Der Ordnername wird automatisch dem Pfad `/docs` vorangestellt.
+`as`
+: Pfad zum Zielordner, relativ zum Ordner `versioned_docs/version-<klasse>/`.
+: *alias* `section` (kann gleichbedeutend zu `as` verwendet werden)
+
+## CLI
+
+Um das Material entsprechend der Konfiguration im `material.config.yaml` in die jeweiligen Klassenordner zu kopieren, muss folgender Befehl ausgeführt werden:
+
+```bash
+yarn run sync
+```
+
+:::details[Scripts in package.json]
+Folgende Einträge können in der `package.json` hinzugefügt werden, um die Nutzung zu vereinfachen:
+```json
+{
+    "scripts": {
+        "sync": "yarn workspace @tdev/material-sync sync",
+        "remove": "yarn workspace @tdev/material-sync run remove",
+        "postremove": "yarn workspace @tdev/material-sync sync",
+        "precleanup": "yarn workspace @tdev/material-sync restore",
+        "cleanup": "yarn workspace @tdev/material-sync cleanup",
+        "addClass": "yarn workspace @tdev/material-sync run addClass",
+        "add": "yarn workspace @tdev/material-sync run add",
+        "postadd": "yarn workspace @tdev/material-sync sync"
+    }
+}
+```
+
+Zudem muss sichergestellt werden, dass die Dokumente vor einem Build synchronisiert werden - dies kann entweder in der CI/CD-Pipeline oder in einem Prebuild-Skript geschehen. Beispielsweise kann folgendes in der `package.json` hinzugefügt werden:
+
+```json
+{
+    "scripts": {
+        "prebuild": "yarn workspace @tdev/material-sync sync"        
+    }
+}
+```
+:::
+
+### Material Hinzufügen
+Um die Inhalte für Klassen leichter zu konfigurieren, kann über die Kommandozeile wie folgt vorgegangen werden:
+
+```bash
+# add /OF-BYOD-Basics to 28Ga & 28Gb as /OF-BYOD-Basics
+yarn run add docs/OF-BYOD-Basics/ --to="28Ga,28Gb"   
+# add /OF-BYOD-Basics to 28Ga & 28Gb as /01-BYOD
+yarn run add docs/OF-BYOD-Basics/ --to="28Ga,28Gb" --as="01-BYOD" 
+# ignoriert _category_.json und alle .txt-Dateien im Quellordner
+yarn run add docs/OF-BYOD-Basics/ --to="28Ga,28Gb" --as="01-BYOD" --ignore="_category_.json,*.txt"
+```
+
+:::tip[Autovervollständigung von Pfaden]
+Bash ermöglich das Autovervollständigen von Pfaden und Dateinamen mit der [[tab]]-Taste. Dies kann beim Tippen von Pfaden sehr hilfreich sein.
+:::
+
+### Material synchronisieren
+
+Das Material wird entsprechend der Konfiguration im `material.config.yaml` in die jeweiligen Klassenordner kopiert. Dies kann über die Kommandozeile wie folgt ausgeführt werden:
+
+```bash
+yarn run sync
+```
+
+### [Dev] Material aufräumen
+
+Um im Entwicklungsprozess die Aufstartzeit zu verkürzen, können die übers `material.config.yaml` konfigurierten Inhalte in den Klassenordnern gelöscht werden. Dies kann über die Kommandozeile wie folgt ausgeführt werden:
+
+```bash
+yarn run cleanup
+```
+
+### Material aus der Konfiguration entfernen
+Um Inhalte aus der Konfiguration zu entfernen, kann über die Kommandozeile wie folgt vorgegangen werden:
+
+```bash
+yarn run remove docs/OF-BYOD-Basics/ --from="28Ga,28Gb"
+```
+
+Alternativ können auch die entsprechenden Zeilen aus dem `material.config.yaml` gelöscht werden.
+
+## Neue Klasse hinzufügen
+
+Um eine neue Klasse hinzuzufügen, kann über die Kommandozeile wie folgt vorgegangen werden:
+
+```bash
+yarn run addClass 30Ga
+```
+
+oder für mehrere Klassen gleichzeitig:
+
+```bash
+yarn run addClass 30Ga,30Gb,30Gc
+```

packages/tdev/material-sync/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@tdev/material-sync",
+  "version": "1.0.0",
+  "description": "Material synchronization scripts for teaching documentation",
+  "type": "module",
+  "private": true,
+  "scripts": {
+    "sync": "tsx src/sync.ts",
+    "add": "tsx src/add.ts",
+    "remove": "tsx src/remove.ts",
+    "cleanup": "tsx src/cleanup.ts",
+    "restore": "tsx src/restore.ts",
+    "addClass": "tsx src/add_class.ts"
+  },
+  "dependencies": {
+  },
+  "devDependencies": {
+    "@types/js-yaml": "^4.0.9",
+    "@types/minimist": "^1.2.5",
+    "@types/node": "^22.0.0",
+    "@types/rsync": "^0.4.36",
+    "js-yaml": "^4.1.1",
+    "minimist": "^1.2.8",
+    "rsync": "^0.6.1",
+    "tsx": "^4.20.3",
+    "typescript": "^6.0.2"
+  }
+}

packages/tdev/material-sync/src/add.ts

@@ -0,0 +1,74 @@
+import fs from 'node:fs';
+import { exit } from 'node:process';
+import minimist from 'minimist';
+import {
+    DOC_PATHS,
+    loadMaterialConfig,
+    relative2Doc,
+    REPO_ROOT,
+    resolveMaterialConfig,
+    saveMaterialConfig
+} from './helpers.js';
+
+process.chdir(REPO_ROOT);
+
+const configs = loadMaterialConfig();
+const argv = minimist(process.argv.slice(2));
+
+if (argv.help) {
+    console.log(`
+yarn run add [source] [[--to="v1,v2"]] [[--as="destination-name"]] [[--ignore="file1,file2"]]
+
+examples:
+
+yarn run add docs/byod-basics/v24/ --to="24a,24b"   // --> adds /byod-basics/v24 to 24a & 24b
+yarn run add docs/byod-basics/v24/ --to="24a,24b" --as="My-Material" // --> adds /byod-basics to 24a & 24b
+yarn run add docs/byod-basics/v24/ --to="24a,24b" --as="My-Material" --ignore="_category_.json,*.txt"
+`);
+    exit(0);
+}
+
+let src: string = argv._[0];
+
+const pathStart = DOC_PATHS.find((p) => src.startsWith(p));
+
+if (!pathStart && !src.startsWith('/')) {
+    src = `${DOC_PATHS[0]}${src}`;
+}
+
+const isDir = fs.lstatSync(src).isDirectory();
+if (isDir && !src.endsWith('/')) {
+    src = src + '/';
+}
+
+const klassen = argv.to ? (argv.to as string).split(',') : Object.keys(configs);
+const asPath = argv.as || argv.name || relative2Doc(src);
+let ignore: string[] = [];
+
+if (argv.ignore) {
+    ignore = (argv.ignore as string)
+        .split(',')
+        .map((p) => p.replace(/^\/+/, '')) // remove '/' at the start
+        .map((p) => p.replace(src, '')); // remove relative path if present
+}
+
+klassen.forEach((klass) => {
+    if (!Object.keys(configs).includes(klass)) {
+        console.log(`⚠️ 
+        Klasse not found, skipping: ${klass}
+        `);
+        return;
+    }
+    configs[klass] = configs[klass].filter((_config) => {
+        const config = resolveMaterialConfig(klass, _config);
+        if (config.from === src) {
+            console.log('ℹ️  Modify old source: ', config.from);
+            return false;
+        }
+        return true;
+    });
+
+    configs[klass].push({ from: src, as: asPath, ignore: ignore });
+});
+
+saveMaterialConfig(configs);