Add markdown tree plugin

Author: leeyi45

docs/.vitepress/config.ts

@@ -1,4 +1,5 @@
 // Vitepress config
+import { directoryTreePlugin } from '@sourceacademy/markdown-plugin-directory-tree';
 import { defineConfig, type UserConfig } from 'vitepress';
 import { groupIconMdPlugin, groupIconVitePlugin } from 'vitepress-plugin-group-icons';
 import { withMermaid } from 'vitepress-plugin-mermaid';
@@ -16,6 +17,10 @@ const vitepressOptions: UserConfig = {
   markdown: {
     config(md) {
       md.use(groupIconMdPlugin);
+      md.use(directoryTreePlugin);
+    },
+    languageAlias: {
+      dirtree: 'yml'
     }
   },
   outDir: `${import.meta.dirname}/../../build/devdocs`,
@@ -63,11 +68,11 @@ const vitepressOptions: UserConfig = {
         items: [
           {
             text: 'Build Tools',
-            link: '/buildtools'
+            link: '/buildtools/'
           },
           {
             text: 'Repo Tools',
-            link: '/repotools'
+            link: '/repotools/'
           },
         ]
       }

docs/package.json

@@ -17,5 +17,8 @@
     "vitepress-plugin-group-icons": "^1.6.1",
     "vitepress-plugin-mermaid": "^2.0.17",
     "vitepress-sidebar": "^1.31.1"
+  },
+  "devDependencies": {
+    "@sourceacademy/markdown-plugin-directory-tree": "workspace:^"
   }
 }

docs/src/buildtools/5-builders/2-docs.md

@@ -3,28 +3,25 @@
 There are two types of documentation used by Source, which are the jsons and the HTML documentation. Both are built using the [`typedoc`](https://typedoc.org) tool. By reading comments and type annotations, `typedoc` is able to generate both human readable documentation and documentation in the form of JSON.
 
 ## Typedoc Overview
-Typedoc has been configured to use the [`package` entry point strategy](https://typedoc.org/documents/Options.Input.html#packages). To make sure that each bundle's documentation is generated with the proper name, each bundle's `tsconfig.json` contains
-a `typedocOptions` section which minimally, has the name of the bundle. Using the `package` strategy allows each bundle to customize its own `typedoc` options this way.
+Documentation generation is a two-step process:
 
-Typedoc is initialized with the following options:
+Firstly, the `buildtools build docs` is called on each bundle. This produces two JSON files:
 
-<<< ../../../../lib/buildtools/src/build/docs/docsUtils.ts#commonOpts
+1. `build/jsons/[bundle_name].json`, which is the JSON documentation used by `js-slang` and the frontend
+2. `docs.json`, which is JSON documentation format used by `typedoc` to generate the HTML documentation later
 
-The package options are applied to each bundle, while the common options are used overall.
-
-Initializing `typedoc` returns an [`Application`](https://typedoc.org/api/classes/Application.html) object, which can then be used to generate a [`ProjectReflection`](https://typedoc.org/api/classes/Models.ProjectReflection.html). The reflection always contains more reflection models
-as its children, each of which represents a different bundle.
+Second, `buildtools manifest` is called, which then takes the `docs.json` files from each bundle and uses the [`merge` entry point strategy](https://typedoc.org/documents/Options.Input.html#merge) to create the HTML
+documentation
 
 > [!NOTE]
 > Since type checking is supposed to be performed by `tsc`, `skipErrorChecking` has been set to true. This means that if there are type errors in the source files being processed,
 > `typedoc` simply returns `undefined` when `Application.convert` is called.
 
+This allows each bundle to have its own Typedoc option set.
+
 ## HTML Generation
 It is not possible to generate the HTML documentation on a per-bundle basis. Thus, when HTML documentation needs to be regenerated, the source files of every single bundle needs to be processed.
 
 ## JSON Generation
 `typedoc` represents each bundle as a [`DeclarationReflection`](https://typedoc.org/api/classes/Models.DeclarationReflection.html) internally. Each of these `DeclarationReflection`s contains an array of "children" elements which
 represents that bundle's exports. Each of these elements is parsed by various parsers to produce the desired documentation object, which is then written to disk after converted into a JSON string.
-
-It is possible to generate the JSON documentation of each bundle separately. Hence, the JSON builder doesn't initialize `typedoc`, leaving the caller to choose between initializing `typedoc` for all bundles at once
-or just for that single bundle.

docs/src/buildtools/index.md

@@ -20,24 +20,42 @@ The build tools are comprised of several sections:
   - Code for the template command
 
 ## Structure of the Build Tools package
-```txt
-uildtools
-├── bin
-│   ├── templates                     // Actual template files, retrieved at runtime
-│   ├── docsreadme.md                 // Docs HTML readme, retrieved at runtime
-│   └── index.js                      // The compiled buildtools
-├── src
-│   ├── ___test_mocks__               // Contains a set of mock bundles and tabs for testing
-│   ├── build
-│   │   ├── docs                      // Docs Builders
-│   │   ├── modules
-│   │   │   ├── bundle                // Bundle Builder
-│   │   │   ├── tab                   // Tab Builder
-│   │   │   └── manifest.schema.json  // Schema used to validate bundle manifests
-│   │   └── manifest                  // Code related to manipulating manifests
-│   ├── commands                      // Code where command handlers are defined
-│   ├── prebuild                      // Code for running ESLint and tsc
-│   ├── templates                     // Code for the template commands
-│   └── testing.ts                    // Code for running Vitest from Node
-└── workspacer.py                     // Python code for updating JSON files across bundles and tabs
+```dirtree
+path: ../../../lib/buildtools/
+children:
+  - name: bin
+    children:
+      - name: templates
+        comment: Actual template files, retrieved at runtime
+      - name: docsreadme.md
+        comment: Docs HTML readme, retrieved at runtime
+      - name: index.js
+        comment: The compiled and bundled buildtools
+  - name: src
+    children:
+      - name: __tests_mocks__
+        comment: Contains a set of mock bundles and tabs for testing
+      - name: build
+        children:
+          - name: docs
+            comment: Builders for HTML and JSON documentation
+          - name: modules
+            comment: Builders for bundles and tabs
+            children:
+              - name: manifest.schema.json
+                comment: Schema used to validate bundle manifests
+              - name: all.ts
+                comment: Combined builder for a specific bundle or tab
+              - name: manifest.ts
+                comment: Code for working with bundle manifests and bundle/tab resolution
+      - name: commands
+        comment: Code where command handlers are defined
+      - name: prebuild
+        comment: Code for running ESLint and tsc, both separately and in parallel
+      - name: templates
+        comment: Code for template commands
+      - name: testing.ts
+        comment: Code for running Vitest from NodeJS
+  - name: workspacer.py
+    comment: Python code for updating JSON files across bundles and tabs
 ```

docs/src/modules/2-bundle/1-overview/1-overview.md

@@ -7,17 +7,23 @@ For example, the `binary_tree` module may want to provide an abstraction for Sou
 ## Bundle Directory Structure Overview
 
 The typical bundle structure for a bundle is shown below. Each section will have its own explanation.
-```txt
-bundle_name             // Name of the root folder is the name of the bundle
-├── src
-│   ├── __tests__       // Folder containing unit tests
-│   │   └── index.ts    // File containing unit tests
-│   ├── index.ts        // Entry Point
-│   ├── functions.ts    // Example file
-│   └── ....            // Other files your bundle may use
-├── package.json        // Package Manifest
-├── manifest.json       // Bundle Manifest
-└── tsconfig.json       // Typescript Configuration
+```dirtree
+name: bundle_name
+children:
+  - name: src
+    children:
+    - name: __tests__
+      comment: Folder containing unit tests
+    - name: index.ts
+      comment: Entry point
+    - name: functions.ts
+      comment: Example file
+  - name: package.json
+    comment: Package Manifest; Used by Yarn
+  - name: manifest.json
+    comment: Bundle Manifest
+  - name: tsconfig.json
+    comment: Typescript Configuration
 ```
 
 > [!NOTE]

docs/src/modules/3-tabs/1-overview.md

@@ -5,37 +5,44 @@ be used with the [frontend](https://github.com/source-academy/frontend).
 ## Tab Directory Structure Overview
 The typical tab directory structure is shown below.
 
-```txt
-TabName
-├── index.tsx
-├── tsconfig.json
-└── package.json
+```dirtree
+name: TabName
+children:
+  - index.tsx
+  - tsconfig.json
+  - package.json
 ```
 
 Alternatively, should you wish to use a `src` folder:
-```txt
-TabName
-├── src
-│   ├── index.tsx
-│   ├── component.tsx
-│   └── ...
-├── tsconfig.json
-└── package.json
+```dirtree
+name: TabName
+children:
+  - name: src
+    children:
+      - index.tsx
+      - component.tsx
+  - tsconfig.json
+  - package.json
 ```
 > [!NOTE]
 > The name of the root folder will be the name of the tab
 
 Tabs also support testing (using both `.ts` and `.tsx` extensions):
-```txt
-TabName
-├── src
-│   ├── __tests__
-│   │     └── test.tsx
-│   ├── index.tsx
-│   ├── component.tsx
-│   └── ...
-├── tsconfig.json
-└── package.json
+```dirtree
+name: TabName
+children:
+  - name: src
+    children:
+      - name: __tests__
+        children:
+          - name: test.tsx
+            comment: You can use a tsx file
+          - name: test2.ts
+            comment: Or a regular ts file
+      - index.tsx
+      - component.tsx
+  - tsconfig.json
+  - package.json
 ```
 
 The name of the tab is what you should refer to the tab as in its parent bundle's manifest:

docs/src/repotools/docserver/docserver.md renamed to docs/src/repotools/docserver/1-overview.md

@@ -1,3 +1,6 @@
+---
+title: Overview
+---
 # Developer Documentation Server
 
 Originally most of the developer documentation was contained within the Github repository's wiki. However, as the documentation became more comprehensive in scope and complex in design,
@@ -13,26 +16,32 @@ some folder have contents that are labelled `1-something`, `2-something` etc. Ea
 
 Folders produce item groups, the name of which can be customized using an `index.md` file within that folder.
 
-```txt
-bundles
-├── index.md
-├── 1-getting-started
-│   ├── 1-overview.md
-│   ├── 2-start.md
-│   ├── 3.cheat.md
-│   ├── 4-faq.md
-│   └── index.md
-└── 2-bundle
-    ├── 1-overview
-    │   └── 1-overview.md
-    ├── 2-creating
-    │   └── 2-creating.md
-    ├── 3-editing.md
-    ├── 4-documentation
-    │   └── 4-documentation.md
-    ├── 5-type_map.md
-    ├── 6-compiling.md
-    └── index.md
+```dirtree
+name: bundles
+children:
+    - index.md
+    - name: 1-getting-started
+      children:
+        - 1-overview.md
+        - 2-start.md
+        - 3-cheat.md
+        - 4-faq.md
+        - index.md
+    - name: 2-bundle
+      children:
+        - name: 1-overview
+          children:
+            - 1-overview.md
+        - name: 2-creating.md
+          children:
+            - 2-creating.md
+        - 3-editing.md
+        - name: 4-documentation
+          children:
+            - 4-documentation.md
+        - 5-type_map.md
+        - 6-compiling.md
+        - index.md
 ```
 
 The above file structure produces the menu below:
@@ -41,7 +50,7 @@ The above file structure produces the menu below:
 Each item takes its title value from either the frontmatter (if available) or the first heading of each page.
 
 `index.md` files are only used to title the menus, they are not intended for navigation, though are navigable to if the user enters the address manually, so it is still recommended to keep some basic
-documentation in those pages or create rewrites so that users are automatically redirected away from those pages. Here are the contents of `2-bundle/index.md`:
+documentation in those pages or create rewrites so that users are automatically redirected away from those pages. Here are the contents of <nobr><code>2-bundle/index.md</code></nobr>:
 
 <<< ../../modules/2-bundle/index.md
 
@@ -78,4 +87,4 @@ this
 └── tree
     └── diagram
 ```
-were generated from [this website](https://tree.nathanfriend.com/)
+are generated via their own markdown plugin, the details of which can be found [here](./2-dirtree).