Website for Theia Trace Extension documentation

.gitignore

@@ -5,6 +5,7 @@
 !examples/*/scripts/
 *.log
 *.tsbuildinfo
+.DS_Store
 .browser_modules/
 /.venv/
 /packages/base/lib/

doc/web-doc/.eslintignore

@@ -0,0 +1,13 @@
+.DS_Store
+node_modules
+/build
+/.svelte-kit
+/package
+.env
+.env.*
+!.env.example
+
+# Ignore files for PNPM, NPM and YARN
+pnpm-lock.yaml
+package-lock.json
+yarn.lock

doc/web-doc/.eslintrc.cjs

@@ -0,0 +1,15 @@
+module.exports = {
+	root: true,
+	extends: ['eslint:recommended', 'prettier'],
+	plugins: ['svelte3'],
+	overrides: [{ files: ['*.svelte'], processor: 'svelte3/svelte3' }],
+	parserOptions: {
+		sourceType: 'module',
+		ecmaVersion: 2020
+	},
+	env: {
+		browser: true,
+		es2017: true,
+		node: true
+	}
+};

doc/web-doc/.gitignore

@@ -0,0 +1,11 @@
+# LC_COLLATE=C sort .gitignore
+.DS_Store
+.env
+.env.*
+/.svelte-kit
+/build
+/package
+doc-sources
+node_modules
+vite.config.js.timestamp-*
+vite.config.ts.timestamp-*

doc/web-doc/.prettierignore

@@ -0,0 +1,14 @@
+.DS_Store
+doc-sources
+node_modules
+/build
+/.svelte-kit
+/package
+.env
+.env.*
+!.env.example
+
+# Ignore files for PNPM, NPM and YARN
+pnpm-lock.yaml
+package-lock.json
+yarn.lock

doc/web-doc/.prettierrc

@@ -0,0 +1,9 @@
+{
+	"useTabs": true,
+	"singleQuote": true,
+	"trailingComma": "none",
+	"printWidth": 100,
+	"plugins": ["prettier-plugin-svelte"],
+	"pluginSearchDirs": ["."],
+	"overrides": [{ "files": "*.svelte", "options": { "parser": "svelte" } }]
+}

doc/web-doc/README.md

@@ -0,0 +1,48 @@
+# Documentation framework for Theia Trace Extension
+
+## Installation
+
+Requirements: NodeJS on the same version as the one required for [Theia IDE][theia-prereq].
+
+```bash
+cd doc/web-doc
+yarn
+```
+
+> Executing `yarn` from the root of `theia-trace-extension` does not install the dependencies in `doc/web-doc`. The configuration for Lerna to support such a feature may be added in the future.
+
+Run site
+
+```bash
+yarn dev
+```
+
+Or start the server and open the app in a new browser tab
+
+```bash
+yarn dev --open
+```
+
+The site will be running at [localhost, port 5173].
+
+## Development
+
+Run Prettier from the root of the web-doc project (at `doc/web-doc/` from the root of `theia-trace-extension`) using the following commands:
+
+To check code style:
+
+```bash
+yarn lint
+```
+
+To fix code style:
+
+```bash
+yarn format
+```
+
+Website created with [SvelteKit].
+
+[theia-prereq]: https://github.com/eclipse-theia/theia/blob/master/doc/Developing.md#prerequisites
+[sveltekit]: https://kit.svelte.dev
+[localhost, port 5173]: http://localhost:5173

doc/web-doc/doc-loader.js

@@ -0,0 +1,94 @@
+import fs from 'fs-extra';
+import { compareSync } from 'dir-compare';
+import { once } from 'node:events';
+import { createInterface } from 'node:readline';
+
+const src = '../adr/';
+const dest = 'doc-sources/adr-source/';
+
+const errorCallback = (err) => {
+	if (err) throw err;
+};
+
+const comparisonOptions = {
+	excludeFilter: '.DS_Store',
+	compareSize: true,
+	compareContent: true
+};
+
+// Sanitizer of markdown files
+
+const sanitizer = (chunk) => {
+	return chunk.replace(/{/g, '{').replace(/}/g, '}');
+};
+
+const processLineByLine = async (file) => {
+	try {
+		let result = '';
+		let mermaid = false;
+		let mermaidBlock = '';
+
+		const rl = createInterface({
+			input: file,
+			crlfDelay: Infinity
+		});
+
+		rl.on('line', (line) => {
+			if (mermaid) {
+				mermaidBlock += line + '\n';
+
+				if (line.includes('```')) {
+					mermaid = false;
+					result += sanitizer(mermaidBlock);
+					mermaidBlock = '';
+				}
+			} else {
+				result += line + '\n';
+			}
+
+			if (line.includes('```mermaid')) {
+				mermaid = true;
+			}
+		});
+
+		await once(rl, 'close');
+
+		return result;
+	} catch (err) {
+		console.error(err);
+	}
+};
+
+// Compare folders
+
+if (!fs.existsSync('doc-sources')) {
+	fs.mkdirSync('doc-sources');
+	fs.mkdirSync(dest);
+} else if (!fs.existsSync(dest)) {
+	fs.mkdirSync(dest);
+}
+
+const comparison = compareSync(src, dest, comparisonOptions);
+
+// Copy missing files and folders
+
+if (!comparison.same) {
+	comparison.diffSet.forEach(async (dif) => {
+		if ((dif.state === 'left' || dif.state === 'distinct') && dif.path1 === src) {
+			if (dif.type1 === 'file' && dif.name1.slice(-3) === '.md') {
+				// Remove outdated file
+				if (dif.state === 'distinct') {
+					fs.rmSync(dest + dif.name2, { force: true });
+				}
+
+				// Sanitize Markdown files
+				const file = fs.createReadStream(src + dif.name1, 'utf8');
+				const sanitized = await processLineByLine(file);
+				fs.writeFileSync(dest + dif.name1, sanitized.toString());
+			} else {
+				// Copy
+				fs.copySync(src + dif.name1, dest + dif.name1, { recursive: true }, errorCallback);
+			}
+		}
+	});
+}

doc/web-doc/mdsvex.config.js

@@ -0,0 +1,14 @@
+import remarkMermaid from '@ysuzuki19/remark-mermaid';
+
+const config = {
+	extensions: ['.svelte.md', '.md', '.svx'],
+
+	smartypants: {
+		dashes: 'oldschool'
+	},
+
+	remarkPlugins: [remarkMermaid],
+	rehypePlugins: []
+};
+
+export default config;

doc/web-doc/package.json

@@ -0,0 +1,32 @@
+{
+	"name": "web-doc",
+	"version": "0.0.1",
+	"private": true,
+	"scripts": {
+		"dev": "node doc-loader;vite dev",
+		"build": "vite build",
+		"preview": "vite preview",
+		"lint": "prettier --plugin-search-dir . --check . && eslint .",
+		"format": "prettier --plugin-search-dir . --write .",
+		"load": "node doc-loader"
+	},
+	"devDependencies": {
+		"@sveltejs/adapter-auto": "^1.0.0",
+		"@sveltejs/kit": "^1.0.0",
+		"eslint": "^8.28.0",
+		"eslint-config-prettier": "^8.5.0",
+		"eslint-plugin-svelte3": "^4.0.0",
+		"prettier": "^2.8.0",
+		"prettier-plugin-svelte": "^2.8.1",
+		"svelte": "^3.54.0",
+		"vite": "^4.0.0"
+	},
+	"type": "module",
+	"dependencies": {
+		"@ysuzuki19/remark-mermaid": "^1.0.2",
+		"dir-compare": "^4.0.0",
+		"fs-extra": "^11.1.0",
+		"mdsvex": "^0.10.6",
+		"mermaid": "^9.3.0"
+	}
+}

doc/web-doc/src/app.html

@@ -0,0 +1,12 @@
+<!DOCTYPE html>
+<html lang="en">
+	<head>
+		<meta charset="utf-8" />
+		<link rel="icon" href="%sveltekit.assets%/favicon.png" />
+		<meta name="viewport" content="width=device-width" />
+		%sveltekit.head%
+	</head>
+	<body data-sveltekit-preload-data="hover">
+		<div style="display: contents">%sveltekit.body%</div>
+	</body>
+</html>