Moves ADRs into project and adds ADR's pages

This commit moves the ADR folder into the project, so that the project
can dynamically create pages for them.

New ADRs still can be added just as they were added before: by creating
markdown files inside the ADR folder.

The project automatically renders HTML pages for the ADRs and:

- The sidebar automatically creates buttons for each ADR;
- Mermaid plugin was added to display diagrams inside ADRs;

Signed-off-by: Rodrigo Pinto <[email protected]>

.gitignore

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

.vscode/launch.json

@@ -136,7 +136,7 @@
             "type": "node",
             "request": "launch",
             "name": "Apollo Server (GraphQL ADR)",
-            "cwd": "${workspaceFolder}/doc/adr/0002/graphql-server-prototype",
+            "cwd": "${workspaceFolder}/doc/web-doc/adr/0002/graphql-server-prototype",
             "args": [
                 "index.js"
             ],

README.md

@@ -327,7 +327,7 @@ yarn test --coverage --collectCoverageFrom='src/**/*.ts'
 
 ADRs are [Architectural Decision Records][adr].
 
-* The `./doc/adr` directory was initialized using `adr-init` based on [adr-tools-python][tools].
+* The `./doc/web-doc/adr` directory was initialized using `adr-init` based on [adr-tools-python][tools].
 * The `adr-new` command (from [adr-tools-python][tools]) is used to add new ADRs further.
 * That tool can be installed locally (only once) using [the instructions below](#python-setup).
 * The latter also shows how to activate a Python virtual environment to locally run commands.

doc/web-doc/.prettierignore

@@ -1,4 +1,5 @@
 .DS_Store
+adr
 node_modules
 /build
 /.svelte-kit

doc/web-doc/README.md

@@ -2,36 +2,46 @@
 
 ## Installation
 
-Requirements: NodeJS version 16 or above.
+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 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
 
-# or start the server and open the app in a new browser tab
+```bash
 yarn dev --open
 ```
 
-The site will be running at `http://localhost:5173`.
+The site will be running at [http://localhost:5173](http://localhost:5173).
 
-## Code style
+## Development
 
-Run Prettier from the root.
+Run Prettier from the root using the following commands:
 
-Check code style:
+To check code style:
 
-	yarn lint
+```bash
+yarn lint
+```
 
-Fix code style:
+To fix code style:
 
-	yarn format
+```bash
+yarn format
+```
 
-## Development
+Website created with [SvelteKit].
 
-Website created with [SvelteKit](https://kit.svelte.dev)
+[theia-prereq]: https://github.com/eclipse-theia/theia/blob/master/doc/Developing.md#prerequisites
+[sveltekit]: https://kit.svelte.dev

doc/adr/0006-table-filtering.md → doc/web-doc/adr/0006-table-filtering.md

@@ -35,9 +35,9 @@ sequenceDiagram
     User->>client: open Events Table
     client->>context: create TraceContextComponent
     context->>table: create TableOutputComponent
-    client->>server: POST /experiments/{expUUID}/outputs/table/{outputId}/columns
+    client->>server: POST /experiments/"{"expUUID"}"/outputs/table/"{"outputId"}"/columns
     server->>client: 200: TableColumnHeader[]
-    client->>server: POST /experiments/{expUUID}/outputs/table/{outputId}/lines
+    client->>server: POST /experiments/"{"expUUID"}"/outputs/table/"{"outputId"}"/lines
     Note over client,server: requested_items=list of columnIDs
     Note over client,server: requested_table_count=100
     Note over client,server: requested_table_index=0
@@ -46,7 +46,7 @@ sequenceDiagram
     table->>table: Update table
     table->>table: Update table with nbEvents
     loop while indexingStatus==RUNNING
-        context->>server: GET /experiments/{expUUID}/
+        context->>server: GET /experiments/"{"expUUID"}"/
         server->>context: 200: Experiment
         context->>table: Update TableOutputComponent
         table->>table: this.gridApi.setInfiniteRowCount(this.props.nbEvents);
@@ -73,9 +73,9 @@ sequenceDiagram
     User->>client: open Events Table
     client->>context: create TraceContextComponent
     context->>table: create TableOutputComponent
-    client->>server: POST /experiments/{expUUID}/outputs/table/{outputId}/columns
+    client->>server: POST /experiments/"{"expUUID"}"/outputs/table/"{"outputId"}"/columns
     server->>client: 200: TableColumnHeader[]
-    client->>server: POST /experiments/{expUUID}/outputs/table/{outputId}/lines
+    client->>server: POST /experiments/"{"expUUID"}"/outputs/table/"{"outputId"}"/lines
     Note over client,server: requested_items=list of columnIDs
     Note over client,server: requested_table_count=100
     Note over client,server: requested_table_index=0
@@ -84,7 +84,7 @@ sequenceDiagram
     table->>table: Update table
     table->>table: Update table with nbEvents
     loop while indexingStatus==RUNNING
-        table->>server: GET /experiments/{expUUID}/outputs/table/{outputId}/
+        table->>server: GET /experiments/"{"expUUID"}"/outputs/table/"{"outputId"}"/
         server->>table: 200: DataProviderDescriptor/indexingStatus/nbEvents
         table->>table: this.gridApi.setInfiniteRowCount(experiment.nbEvents);
         table->>table: Update vertical scrollbar
@@ -103,7 +103,7 @@ sequenceDiagram
     User->>table: enter column filter regex
     table->>table: reset nbEvents
     table->>table: Indicate that filter is active
-    table->>server: POST /experiments/{expUUID}/outputs/table/{outputId}/lines
+    table->>server: POST /experiments/"{"expUUID"}"/outputs/table/"{"outputId"}"/lines
     Note over table,server: requested_table_index=startIndex
     Note over table,server: requested_table_count=nbEvents
     Note over table,server: table_filter_expressions=[columnId->regEx,...]
@@ -115,7 +115,7 @@ sequenceDiagram
     table->>table: Update table
     table->>table: Update table with nbEvents
     loop while indexingStatus==RUNNING
-        table->>server: GET /experiments/{expUUID}/outputs/table/{outputId}/
+        table->>server: GET /experiments/"{"expUUID"}"/outputs/table/"{"outputId"}"/
         server->>table: 200: DataProviderDescriptor/indexingStatus/nbEvents
         table->>table: this.gridApi.setInfiniteRowCount(experiment.nbEvents);
         table->>table: Update vertical scrollbar
@@ -130,7 +130,7 @@ The following endpoint needs to be added to the TSP to query the indexing progre
 sequenceDiagram
     participant client as TSP Client
     participant server as Trace Server
-    client->>server: GET /experiments/{expUUID}/outputs/table/{outputId}/
+    client->>server: GET /experiments/"{"expUUID"}"/outputs/table/"{"outputId"}"/
     server->>client: 200: DataProviderEnhanced
 ```
 
@@ -152,7 +152,7 @@ The following query parameters need to be updated to support filtering of the vi
 
 ```mermaid
 sequenceDiagram
-    table->>server: POST /experiments/{expUUID}/outputs/table/{outputId}/lines
+    table->>server: POST /experiments/"{"expUUID"}"/outputs/table/"{"outputId"}"/lines
     Note over table,server: table_filter_expressions=[columnId->regEx,...]
     server->>table: 200: VirtualTableModel
 ```

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

@@ -20,5 +20,10 @@
 		"svelte": "^3.54.0",
 		"vite": "^4.0.0"
 	},
-	"type": "module"
+	"type": "module",
+	"dependencies": {
+		"@ysuzuki19/remark-mermaid": "^1.0.2",
+		"mdsvex": "^0.10.6",
+		"mermaid": "^9.3.0"
+	}
 }

doc/web-doc/src/lib/components/Header.svelte

@@ -6,7 +6,7 @@
 
 <header>
 	<div class="corner">
-    <a href="https://projects.eclipse.org/projects/tools.tracecompass">
+		<a href="https://projects.eclipse.org/projects/tools.tracecompass">
 			<img src={logo} alt="Trace Compass" />
 		</a>
 	</div>

doc/web-doc/src/lib/components/Sidebar.svelte

@@ -1,6 +1,9 @@
 <script>
 	import { page } from '$app/stores';
 	import { goto } from '$app/navigation';
+
+	export let adrs;
+	let showAdrs = false;
 </script>
 
 <div class="sidebar">
@@ -11,12 +14,27 @@
 		<li aria-current={$page.url.pathname === '/about' ? 'page' : undefined}>
 			<button on:click={() => goto('/about')}>About</button>
 		</li>
+		<li>
+			<button class:selected={showAdrs} on:click={() => (showAdrs = !showAdrs)}>ADRs</button>
+		</li>
+		{#if showAdrs}
+			{#each adrs as adr}
+				<li aria-current={$page.url.pathname === '/adr/' + adr.slug ? 'page' : undefined}>
+					<button class="adr">
+						<a href={'/adr/' + adr.slug} target="_self">
+							<div class="link-holder">{adr.slug}</div>
+						</a>
+					</button>
+				</li>
+			{/each}
+		{/if}
 	</ul>
 </div>
 
 <style>
 	.sidebar {
 		width: 10em;
+		min-width: 10em;
 	}
 
 	ul {
@@ -31,6 +49,37 @@
 	button {
 		width: 100%;
 		height: 100%;
-		background: none;
+	}
+
+	button.adr {
+		display: flex;
+		padding: 0;
+	}
+
+	button.adr a {
+		width: 100%;
+		height: 100%;
+		display: flex;
+		color: black;
+		text-decoration: none;
+	}
+
+	button.adr a:visited,
+	button.adr a:link,
+	button.adr a:focus {
+		color: black;
+	}
+
+	button.selected {
+		background: lightgrey;
+		border-width: 0;
+	}
+
+	button:hover {
+		cursor: pointer;
+	}
+
+	.link-holder {
+		margin: auto;
 	}
 </style>

doc/web-doc/src/lib/process-files.js

@@ -0,0 +1,62 @@
+const allAdrFiles = import.meta.glob('/adr/*.md');
+const iterableAdrFiles = Object.entries(allAdrFiles);
+
+export const getAdrsContent = async () => {
+	const allAdrs = await Promise.all(
+		iterableAdrFiles.map(async ([path, resolver]) => {
+			const element = await resolver();
+			const metadata = element.metadata;
+			const content = element.default.render();
+			const slug = path.slice(0, -3).split('/').pop();
+
+			return {
+				metadata,
+				slug,
+				path,
+				content
+			};
+		})
+	);
+
+	return allAdrs;
+};
+
+export const getAdr = async (slug) => {
+	const adr = iterableAdrFiles?.filter(([path]) => {
+		const fileSlug = path.slice(0, -3).split('/').pop();
+
+		return fileSlug === slug;
+	});
+
+	if (adr.length > 0) {
+		const resolver = adr[0][1];
+		const element = await resolver();
+		console.log('resolver', element);
+		//   const content = element.default.render()
+
+		//   return content
+	}
+
+	return adr;
+};
+
+export const getOneAdr = async (slug) => {
+	const allAdrs = await Promise.all(
+		iterableAdrFiles.map(async ([path, resolver]) => {
+			const fileSlug = path.slice(0, -3).split('/').pop();
+			let content = 'empty';
+			if (fileSlug === slug) {
+				console.log('equal', slug, path, resolver);
+				const element = await resolver();
+				content = element.default.render();
+			}
+
+			return {
+				content
+			};
+		})
+	);
+
+	console.log('all adrs', allAdrs);
+	return allAdrs;
+};

doc/web-doc/src/routes/+layout.server.js

@@ -0,0 +1,7 @@
+import { getAdrsContent } from '$lib/process-files';
+
+export async function load() {
+	const adrs = await getAdrsContent();
+
+	return { adrs };
+}

doc/web-doc/src/routes/+layout.svelte

@@ -1,14 +1,16 @@
 <script>
 	import Header from '$lib/components/Header.svelte';
 	import Sidebar from '$lib/components/Sidebar.svelte';
+
+	export let data;
 </script>
 
 <div class="app">
 	<Header />
 
 	<main>
 		<div class="content">
-			<Sidebar />
+			<Sidebar adrs={data.adrs} />
 			<div class="inner-page">
 				<slot />
 			</div>