Skip to content

Commit 2de9bfb

Browse files
committed
Avoid soft breaks
1 parent 420bdfb commit 2de9bfb

File tree

4 files changed

+24
-50
lines changed

4 files changed

+24
-50
lines changed

docs/src/repotools/6-docserver/1-overview.md

Lines changed: 8 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -3,17 +3,15 @@ title: Overview
33
---
44
# Developer Documentation Server
55

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.
87

98
This documentation server is powered by [Vitepress](https://vitepress.dev), which takes Markdown files and renders them into a (mostly) static site.
109

1110
## File Structure
1211

1312
All pages for the server are contained under `src`.
1413

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.
1715

1816
Folders produce item groups, the name of which can be customized using an `index.md` file within that folder.
1917

@@ -50,8 +48,7 @@ The above file structure produces the menu below:
5048

5149
Each item takes its title value from either the frontmatter (if available) or the first heading of each page.
5250

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>:
5552

5653
<<< ../../modules/2-bundle/index.md
5754

@@ -62,21 +59,18 @@ Instead, the links in the sidebar link to the page (if it is a markdown file), o
6259
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.
6360

6461
::: 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.
6763
:::
6864

6965
## Diagrams
7066

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.
7368

7469
## Code Snippets
7570

7671
`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).
7772

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.
8074

8175
## Tree Diagrams
8276

@@ -94,8 +88,6 @@ are generated via their own markdown plugin, the details of which can be found [
9488

9589
## Production Build and Dead Links
9690

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.
9992

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.

docs/src/repotools/6-docserver/2-dirtree.md

Lines changed: 8 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -3,11 +3,9 @@
33
The idea behind this plugin was inspired by [this](https://tree.nathanfriend.com/?) ASCII tree generator.
44

55
::: 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.
87

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.
119

1210
Using the `languageAlias` markdown configuration, we can get Vitepress to highlight and colour the rendered directory trees.
1311
:::
@@ -28,8 +26,7 @@ name: root directory
2826
```
2927
````
3028

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:
3330

3431
````md
3532
``` dirtree
@@ -42,8 +39,7 @@ children:
4239
```
4340
````
4441

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:
4743

4844
```yml
4945
name: item1 # You must provide the name property
@@ -71,8 +67,7 @@ children:
7167
7268
## Path Validation
7369
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.
7671

7772
````md {4}
7873
<!-- Located in docs/index.md -->
@@ -87,16 +82,12 @@ children:
8782
```
8883
````
8984

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`.
9386

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.
9688

9789
> [!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.
10091

10192
If the check fails a warning will be printed to the console stating which files it wasn't able to locate.
10293

docs/src/repotools/7-workflows/1-actions.md

Lines changed: 2 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -10,8 +10,7 @@ makes use of two:
1010
- Initializer Action
1111
- Information Action
1212

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).
1514

1615
## Information Action (`info/action.yml`)
1716

@@ -24,8 +23,7 @@ The information action retrieves information about each package present in the r
2423

2524
In the case of bundles or tabs, it also retrieves the name of the bundle or tab.
2625

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.
2927

3028
This information is used by both the initializer action and the workflows to determine the what tasks need to be executed.
3129

docs/src/repotools/7-workflows/2-pull-request.md

Lines changed: 6 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -10,36 +10,29 @@ This workflow makes use of `matrix` strategy to run the tasks in parallel where
1010

1111
## 1. `find-packages`
1212

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.
1514

1615
> [!INFO]
1716
> The info action runs `git --no-pager diff master [directory]` from a package's root directory to determine if there
1817
> are any changes in the package. Because of this, it is also necessary to run a `git fetch`.
1918
2019
## 2. `libraries`, `bundles` and `tabs`
2120

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.
2422

2523
This means that if the package requires `playwright` to run its tests, it will be installed during the init step.
2624

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.
2926

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.
3228

3329
## 3. `devserver`
3430

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.
3732

3833
## 4. `docserver`
3934

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.
4336

4437
## 5. `repo-tasks`
4538

0 commit comments

Comments
 (0)