You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/src/repotools/6-docserver/1-overview.md
+8-16Lines changed: 8 additions & 16 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -3,17 +3,15 @@ title: Overview
3
3
---
4
4
# Developer Documentation Server
5
5
6
-
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,
7
-
it was necessary to migrate to a more advanced and configurable solution.
6
+
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, it was necessary to migrate to a more advanced and configurable solution.
8
7
9
8
This documentation server is powered by [Vitepress](https://vitepress.dev), which takes Markdown files and renders them into a (mostly) static site.
10
9
11
10
## File Structure
12
11
13
12
All pages for the server are contained under `src`.
14
13
15
-
[`vitepress-sidebar`](https://vitepress-sidebar.cdget.com) is being used to generate the sidebar for the server. This means that entries in the sidebar appear sorted according to the file/folder names from which they originate. This is why
16
-
some folder have contents that are labelled `1-something`, `2-something` etc. Each item's value is taken from file's frontmatter, or if not present, the file's first header.
14
+
[`vitepress-sidebar`](https://vitepress-sidebar.cdget.com) is being used to generate the sidebar for the server. This means that entries in the sidebar appear sorted according to the file/folder names from which they originate. This is why some folder have contents that are labelled `1-something`, `2-something` etc. Each item's value is taken from file's frontmatter, or if not present, the file's first header.
17
15
18
16
Folders produce item groups, the name of which can be customized using an `index.md` file within that folder.
19
17
@@ -50,8 +48,7 @@ The above file structure produces the menu below:
50
48
51
49
Each item takes its title value from either the frontmatter (if available) or the first heading of each page.
52
50
53
-
`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
54
-
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>:
51
+
`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 <nobr><code>2-bundle/index.md</code></nobr>:
55
52
56
53
<<< ../../modules/2-bundle/index.md
57
54
@@ -62,21 +59,18 @@ Instead, the links in the sidebar link to the page (if it is a markdown file), o
62
59
The documentation for `@sourceacademy/modules-lib` is automatically generated by Typedoc. The configuration options for this generation are found in that folder. The documentation for `@sourceacademy/modules-lib` should be built before this server is built.
63
60
64
61
::: details help pls
65
-
Supposedly Vitepress can embed React components, which would be nice for us to have working demonstrations of our React components. Unfortunately, I have never
66
-
been able to get that to work. You can start [here](https://github.com/vuejs/vitepress/discussions/2183) if you want to help figure this out.
62
+
Supposedly Vitepress can embed React components, which would be nice for us to have working demonstrations of our React components. Unfortunately, I have never been able to get that to work. You can start [here](https://github.com/vuejs/vitepress/discussions/2183) if you want to help figure this out.
67
63
:::
68
64
69
65
## Diagrams
70
66
71
-
Diagrams (such as the one seen [here](/buildtools/4-resolution.html#bundle-resolution)) are supported via the [`mermaid`](https://mermaid.js.org) rendering engine and provided with the [Vitepress plugin for mermaid](https://github.com/emersonbottero/vitepress-plugin-mermaid).
72
-
Simply use a Markdown code block with the `mermaid` language tag.
67
+
Diagrams (such as the one seen [here](/buildtools/4-resolution.html#bundle-resolution)) are supported via the [`mermaid`](https://mermaid.js.org) rendering engine and provided with the [Vitepress plugin for mermaid](https://github.com/emersonbottero/vitepress-plugin-mermaid). Simply use a Markdown code block with the `mermaid` language tag.
73
68
74
69
## Code Snippets
75
70
76
71
`vitepress` provides the ability for a Markdown document to "import" a code snippet from an external file. This function is documented [here](https://vitepress.dev/guide/markdown#import-code-snippets).
77
72
78
-
Throughout many files in the repository, you will see VSCode `#region` comments. These comments are used to mark out a VSCode region in Typescript/Javascript and are used by the doc server to extract only
79
-
a specified portion of the code within the file. Do not remove these comments unless absolutely necessary.
73
+
Throughout many files in the repository, you will see VSCode `#region` comments. These comments are used to mark out a VSCode region in Typescript/Javascript and are used by the doc server to extract only a specified portion of the code within the file. Do not remove these comments unless absolutely necessary.
80
74
81
75
## Tree Diagrams
82
76
@@ -94,8 +88,6 @@ are generated via their own markdown plugin, the details of which can be found [
94
88
95
89
## Production Build and Dead Links
96
90
97
-
The preview version of the docs rendered by Vitepress when the `vitepress dev` command is executed is not the final version that is intended to be displayed.
98
-
For this, Vitepress provides the `vitepress build` command, which converts the documentation source into its final, minified HTML form.
91
+
The preview version of the docs rendered by Vitepress when the `vitepress dev` command is executed is not the final version that is intended to be displayed. For this, Vitepress provides the `vitepress build` command, which converts the documentation source into its final, minified HTML form.
99
92
100
-
As part of this process, Vitepress will highlight any "dead" links (i.e links that don't point to anything) and will fail if it finds any. If you're editing
101
-
the documentation, you should run the build command to check for the dead links before pushing to the repository.
93
+
As part of this process, Vitepress will highlight any "dead" links (i.e links that don't point to anything) and will fail if it finds any. If you're editing the documentation, you should run the build command to check for the dead links before pushing to the repository.
Copy file name to clipboardExpand all lines: docs/src/repotools/6-docserver/2-dirtree.md
+8-17Lines changed: 8 additions & 17 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -3,11 +3,9 @@
3
3
The idea behind this plugin was inspired by [this](https://tree.nathanfriend.com/?) ASCII tree generator.
4
4
5
5
::: details Creating a Markdown-It Plugin
6
-
The documentation for developers looking to create a Markdown-It plugin are woefully inadequate. Thus, most of this plugin was written
7
-
based on the implementations of other plugins, such as the Vitepress Mermaid plugin and Vitepress Code snippet plugin.
6
+
The documentation for developers looking to create a Markdown-It plugin are woefully inadequate. Thus, most of this plugin was written based on the implementations of other plugins, such as the Vitepress Mermaid plugin and Vitepress Code snippet plugin.
8
7
9
-
It basically works by detecting when a code block has been assigned the `dirtree` language, parses the code block's content
10
-
as YAML and converts that object into the directory structure that can then be rendered as text.
8
+
It basically works by detecting when a code block has been assigned the `dirtree` language, parses the code block's content as YAML and converts that object into the directory structure that can then be rendered as text.
11
9
12
10
Using the `languageAlias` markdown configuration, we can get Vitepress to highlight and colour the rendered directory trees.
13
11
:::
@@ -28,8 +26,7 @@ name: root directory
28
26
```
29
27
````
30
28
31
-
If you do not specify a name for your root directory, then it will have the default name of `"root"`. Now you can proceed to create
32
-
children elements using a YAML list:
29
+
If you do not specify a name for your root directory, then it will have the default name of `"root"`. Now you can proceed to create children elements using a YAML list:
33
30
34
31
````md
35
32
``` dirtree
@@ -42,8 +39,7 @@ children:
42
39
```
43
40
````
44
41
45
-
Each item can either just be a string entry (like `item0` above), in which case that entry is simply displayed as is, or it can be a
46
-
compound YAML object like `item1` is. The details for such an entry are as follows:
42
+
Each item can either just be a string entry (like `item0` above), in which case that entry is simply displayed as is, or it can be a compound YAML object like `item1` is. The details for such an entry are as follows:
47
43
48
44
```yml
49
45
name: item1 # You must provide the name property
@@ -71,8 +67,7 @@ children:
71
67
72
68
## Path Validation
73
69
74
-
In the case you intend for your displayed directory tree to reflect the structure of an actual directory on disk,
75
-
you can specify a `path` property on the root object. This path is resolved from the file containing the markdown.
70
+
In the case you intend for your displayed directory tree to reflect the structure of an actual directory on disk, you can specify a `path` property on the root object. This path is resolved from the file containing the markdown.
76
71
77
72
````md {4}
78
73
<!-- Located in docs/index.md -->
@@ -87,16 +82,12 @@ children:
87
82
```
88
83
````
89
84
90
-
The plugin will then traverse down the directory structure. For each item, if it has children, it checks that the item corresponds
91
-
to a directory of the same name on disk. In the example above, the plugin would check that `docs/root` was a folder that contained
92
-
either a file or directory called `item0`.
85
+
The plugin will then traverse down the directory structure. For each item, if it has children, it checks that the item corresponds to a directory of the same name on disk. In the example above, the plugin would check that `docs/root` was a folder that contained either a file or directory called `item0`.
93
86
94
-
It would also check that `docs/root/item1` exists and that is is a directory (since it has children elements). This check is recursively
95
-
performed on each subdirectory.
87
+
It would also check that `docs/root/item1` exists and that is is a directory (since it has children elements). This check is recursively performed on each subdirectory.
96
88
97
89
> [!WARNING]
98
-
> This validation is only performed for items that have been specified in the `dirtree`, i.e. it doesn't consider items that are present
99
-
> on disk but aren't listed as an issue.
90
+
> This validation is only performed for items that have been specified in the `dirtree`, i.e. it doesn't consider items that are present on disk but aren't listed as an issue.
100
91
101
92
If the check fails a warning will be printed to the console stating which files it wasn't able to locate.
Copy file name to clipboardExpand all lines: docs/src/repotools/7-workflows/1-actions.md
+2-4Lines changed: 2 additions & 4 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -10,8 +10,7 @@ makes use of two:
10
10
- Initializer Action
11
11
- Information Action
12
12
13
-
Creating custom actions is detailed [here](https://docs.github.com/en/actions/reference/workflows-and-actions/metadata-syntax). The convention for each action is have its metadata file (`action.yml`) in the same
14
-
directory as its source code (if necessary).
13
+
Creating custom actions is detailed [here](https://docs.github.com/en/actions/reference/workflows-and-actions/metadata-syntax). The convention for each action is have its metadata file (`action.yml`) in the same directory as its source code (if necessary).
15
14
16
15
## Information Action (`info/action.yml`)
17
16
@@ -24,8 +23,7 @@ The information action retrieves information about each package present in the r
24
23
25
24
In the case of bundles or tabs, it also retrieves the name of the bundle or tab.
26
25
27
-
In case of changes to the lockfile, it also determines which packages need to be rebuilt. This can happen when dependencies of dependencies change,
28
-
so no change is present in the package's source code itself, but the lockfile itself has changed.
26
+
In case of changes to the lockfile, it also determines which packages need to be rebuilt. This can happen when dependencies of dependencies change, so no change is present in the package's source code itself, but the lockfile itself has changed.
29
27
30
28
This information is used by both the initializer action and the workflows to determine the what tasks need to be executed.
Copy file name to clipboardExpand all lines: docs/src/repotools/7-workflows/2-pull-request.md
+6-13Lines changed: 6 additions & 13 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -10,36 +10,29 @@ This workflow makes use of `matrix` strategy to run the tasks in parallel where
10
10
11
11
## 1. `find-packages`
12
12
13
-
This job executes first, using the [Information Action](./1-actions.md#information-action-infoactionyml). The action returns
14
-
all the necessary information for the subsequent jobs to execute their tasks.
13
+
This job executes first, using the [Information Action](./1-actions.md#information-action-infoactionyml). The action returns all the necessary information for the subsequent jobs to execute their tasks.
15
14
16
15
> [!INFO]
17
16
> The info action runs `git --no-pager diff master [directory]` from a package's root directory to determine if there
18
17
> are any changes in the package. Because of this, it is also necessary to run a `git fetch`.
19
18
20
19
## 2. `libraries`, `bundles` and `tabs`
21
20
22
-
These three jobs are matrix jobs that run tasks for the individual packages. If the package has changes, then
23
-
the job will run tests and `tsc` for the package.
21
+
These three jobs are matrix jobs that run tasks for the individual packages. If the package has changes, then the job will run tests and `tsc` for the package.
24
22
25
23
This means that if the package requires `playwright` to run its tests, it will be installed during the init step.
26
24
27
-
These jobs have the `fail-fast` option set to `false`, so a single job failing doesn't mean that the rest of the jobs
28
-
in the workflow get cancelled.
25
+
These jobs have the `fail-fast` option set to `false`, so a single job failing doesn't mean that the rest of the jobs in the workflow get cancelled.
29
26
30
-
For libraries in particular, the job is run with both the `ubuntu-latest` and `windows-latest` OSes. This makes sure that
31
-
our libraries are compatibile with both Windows and POSIX-Compliant operating systems.
27
+
For libraries in particular, the job is run with both the `ubuntu-latest` and `windows-latest` OSes. This makes sure that our libraries are compatibile with both Windows and POSIX-Compliant operating systems.
32
28
33
29
## 3. `devserver`
34
30
35
-
The `devserver` jobs only executes if there were changes within the dev server. Since it relies on bundles and tabs being
36
-
compiled, it does rely on both the `bundles` and the `tabs` jobs to have completed.
31
+
The `devserver` jobs only executes if there were changes within the dev server. Since it relies on bundles and tabs being compiled, it does rely on both the `bundles` and the `tabs` jobs to have completed.
37
32
38
33
## 4. `docserver`
39
34
40
-
The `docserver` job only executes if there were changes made to the modules library or the docs themselves. It doesn't
41
-
deploy the docs here, so it the call to `yarn build` only serves as to way to check that the docs can be generated without errors
42
-
like dead links.
35
+
The `docserver` job only executes if there were changes made to the modules library or the docs themselves. It doesn't deploy the docs here, so it the call to `yarn build` only serves as to way to check that the docs can be generated without errors like dead links.
0 commit comments