Skip to content
This repository was archived by the owner on Apr 13, 2025. It is now read-only.

Commit 7d13969

Browse files
hlxidhlxid
authored
Merge pull request #79 from Tim-Tech-Dev/maintenance/add-documentation-guide
Add Documentation Guide
2 parents 94bafab + d236919 commit 7d13969

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

49 files changed

+1203
-581
lines changed

‎.gitignore

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,6 @@
11
build/
22
.idea
3-
.vscode
3+
.vscode/*
4+
!.vscode/extensions.json
5+
!.vscode/tasks.json
6+
!.vscode/settings.json

‎.ignore-files.txt renamed to ‎.prettierignore

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,2 @@
11
docs/dependencies.md
2-
docs/services.md
2+
docs/services.md

‎.vscode/extensions.json

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
{
2+
"recommendations": [
3+
"davidanson.vscode-markdownlint",
4+
"esbenp.prettier-vscode",
5+
"jebbs.plantuml",
6+
"valentjn.vscode-ltex",
7+
"yzhang.markdown-all-in-one",
8+
"jebbs.markdown-extended"
9+
]
10+
}

‎.vscode/settings.json

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
{
2+
"editor.formatOnSave": true,
3+
"editor.defaultFormatter": "esbenp.prettier-vscode",
4+
"markdownExtended.disabledPlugins": "table-of-contents,footnote,abbr,deflist,sup,sub,checkbox,attrs,kbd,underline,multimd-table,container,mark",
5+
"ltex.language": "en-GB",
6+
"ltex.checkFrequency": "edit",
7+
// This could cause more false positives
8+
"ltex.additionalRules.enablePickyRules": true,
9+
"ltex.hiddenFalsePositives": {
10+
"en-GB": [
11+
// nodecg-io will always be written lowercease
12+
"{'rule': 'UPPERCASE_SENTENCE_START', 'sentence': '^nodecg-io'}",
13+
// Admonition markers are not recognised by the Markdown parser of LTeX
14+
"{'rule': 'PUNCTUATION_PARAGRAPH_END', 'sentence': '^ATTENTION'}",
15+
"{'rule': 'PUNCTUATION_PARAGRAPH_END', 'sentence': '^CAUTION'}",
16+
"{'rule': 'PUNCTUATION_PARAGRAPH_END', 'sentence': '^DANGER'}",
17+
"{'rule': 'PUNCTUATION_PARAGRAPH_END', 'sentence': '^ERROR'}",
18+
"{'rule': 'PUNCTUATION_PARAGRAPH_END', 'sentence': '^EXAMPLE'}",
19+
"{'rule': 'PUNCTUATION_PARAGRAPH_END', 'sentence': '^HINT'}",
20+
"{'rule': 'PUNCTUATION_PARAGRAPH_END', 'sentence': '^IMPORTANT'}",
21+
"{'rule': 'PUNCTUATION_PARAGRAPH_END', 'sentence': '^NOTE'}",
22+
"{'rule': 'PUNCTUATION_PARAGRAPH_END', 'sentence': '^TIP'}",
23+
"{'rule': 'PUNCTUATION_PARAGRAPH_END', 'sentence': '^WARNING'}",
24+
"{'rule': 'PUNCTUATION_PARAGRAPH_END', 'sentence': '^ADMONITION'}"
25+
]
26+
}
27+
}

‎.vscode/tasks.json

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
{
2+
// See https://code.visualstudio.com/docs/editor/tasks
3+
// for the documentation about the tasks.json format
4+
"version": "2.0.0",
5+
"tasks": [
6+
{
7+
"label": "mkdocs serve locally",
8+
"detail": "mkdocs serve",
9+
"type": "shell",
10+
"command": "mkdocs serve",
11+
"group": {
12+
"kind": "build",
13+
"isDefault": true
14+
},
15+
"presentation": {
16+
"reveal": "always",
17+
"panel": "new"
18+
},
19+
"dependsOn": [
20+
"npm: format",
21+
"npm: lint"
22+
]
23+
},
24+
{
25+
"type": "npm",
26+
"script": "format",
27+
"problemMatcher": [],
28+
"label": "npm: format",
29+
"detail":"prettier -w **.md",
30+
"group": "test",
31+
"presentation": {
32+
"reveal": "never",
33+
"panel": "shared",
34+
"revealProblems": "onProblem"
35+
},
36+
},
37+
{
38+
"type": "npm",
39+
"script": "lint",
40+
"problemMatcher": [],
41+
"label": "npm: lint",
42+
"detail": "markdownlint -p .prettierignore .",
43+
"group": "test",
44+
"presentation": {
45+
"reveal": "never",
46+
"panel": "shared",
47+
"revealProblems": "onProblem"
48+
}
49+
}
50+
]
51+
}

‎docs/contribute/contribute.md

Lines changed: 63 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,23 @@
11
# How to contribute
22

3-
There are many ways to contribute to nodecg-io: logging bugs, submitting pull requests, reporting issues, and creating suggestions.
4-
5-
First you'll need an installation of nodecg-io. Please refer to the [installation guide](../getting_started/install.md) and create a development installation.
6-
The CLI asks you whether you want to clone the documentation. It's highly recommended that you do that and update the documentation as you add new services or features.
7-
To be able to create Pull Requests you should fork the corresponding repositories and add them as a remote (update URL for e.g., documentation repository):
3+
There are many ways to contribute to nodecg-io: logging bugs, submitting pull
4+
requests, reporting issues, and creating suggestions. You can also contribute to
5+
this [documentation](docs_setup.md).
6+
7+
First you'll need an installation of nodecg-io. Please refer to the
8+
[installation guide](../getting_started/install.md) and create a development
9+
installation. The CLI asks you whether you want to clone the documentation. It's
10+
highly recommended that you do that and update the documentation as you add new
11+
services or features. To be able to create Pull Requests you should fork the
12+
corresponding repositories and add them as a remote (update URL for e.g.,
13+
documentation repository):
814

915
```shell
1016
git remote add fork https://github.com/[YOUR_USERNAME]/nodecg-io.git
1117
```
1218

13-
Then you can create a new branch, do your changes, create commits and publish the branch to your fork using the following command:
19+
Then you can create a new branch, do your changes, create commits and publish
20+
the branch to your fork using the following command:
1421

1522
```shell
1623
git push fork my-branch
@@ -20,30 +27,36 @@ git push fork my-branch
2027

2128
### VS Code
2229

23-
In Visual Studio Code you can start the build task with
24-
<kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>B</kbd> (<kbd>CMD</kbd>+<kbd>Shift</kbd>+<kbd>B</kbd> on macOS).
25-
The incremental builder will do an initial full build.
26-
The watch builder will watch for file changes and compile those changes incrementally, giving you a fast, iterative coding experience.
27-
It will even stay running in the background if you close VS Code.
28-
You can resume it by starting the build task with
29-
<kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>B</kbd> (<kbd>CMD</kbd>+<kbd>Shift</kbd>+<kbd>B</kbd>) again.
30-
You can kill the build task by pressing <kbd>Ctrl</kbd>+<kbd>D</kbd> in the task terminal (<kbd>CMD</kbd>+<kbd>D</kbd>) on macOS.
31-
Errors and warnings will be shown in the status bar at the bottom left of the editor. You can view the error list using `View | Errors and Warnings` or pressing <kbd>Ctrl</kbd>+<kbd>P</kbd> and then <kbd>!</kbd> (<kbd>CMD</kbd>+<kbd>P</kbd> and <kbd>!</kbd> on macOS)
30+
In Visual Studio Code you can start the build task with <kbd>Ctrl</kbd> +
31+
<kbd>Shift</kbd> + <kbd>B</kbd> (<kbd>CMD</kbd> + <kbd>Shift</kbd> +
32+
<kbd>B</kbd> on macOS). The incremental builder will do an initial full build.
33+
The watch builder will watch for file changes and compile those changes
34+
incrementally, giving you a fast, iterative coding experience. It will even stay
35+
running in the background if you close VS Code. You can resume it by starting
36+
the build task with <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>B</kbd>
37+
(<kbd>CMD</kbd> + <kbd>Shift</kbd> + <kbd>B</kbd>) again.
38+
You can kill the build task by pressing <kbd>Ctrl</kbd> + <kbd>D</kbd> in the
39+
task terminal (<kbd>CMD</kbd> + <kbd>D</kbd>) on macOS.
40+
Errors and warnings will be shown in the status bar at the bottom left of the
41+
editor. You can view the error list using `View | Errors and Warnings` or
42+
pressing <kbd>Ctrl</kbd> + <kbd>P</kbd> and then <kbd>!</kbd> (or
43+
<kbd>CMD</kbd> + <kbd>P</kbd> and <kbd>!</kbd> on macOS).
3244

3345
### Terminal
3446

3547
You can also use you terminal to build nodecg-io:
3648

37-
```
49+
```shell
3850
cd path/to/nodecg-io
3951
npm run build
4052
```
4153

42-
To do a full rebuild instead of just an incremental build you can use `npm run rebuild`.
54+
To do a full rebuild instead of just an incremental build you can use
55+
`npm run rebuild`.
4356

4457
The watch builder can be activated here too:
4558

46-
```
59+
```shell
4760
cd path/to/nodecg-io
4861
npm run watch
4962
```
@@ -54,36 +67,58 @@ To test the changes you simply need to start/restart NodeCG.
5467

5568
## Adding dependencies to packages
5669

57-
This project uses [npm workspaces](https://docs.npmjs.com/cli/v7/using-npm/workspaces/) to manage our monorepo, and most importantly link all our packages together.
58-
Because of linking you should not use `npm install xyz --save` to add dependencies because npm can't get the development version of internal packages like `nodecg-io-core`. Doing so will result in an error and break the link.
59-
Instead, you should edit the `package.json` directly using a text editor and the run `npm install` in the repository root.
70+
This project uses
71+
[npm workspaces](https://docs.npmjs.com/cli/v7/using-npm/workspaces/) to manage
72+
our monorepo, and most importantly link all our packages together. Because of
73+
linking you should not use `npm install xyz --save` to add dependencies because
74+
npm can't get the development version of internal packages like
75+
`nodecg-io-core`. Doing so will result in an error and break the link. Instead,
76+
you should edit the `package.json` directly using a text editor and the run
77+
`npm install` in the repository root.
6078

6179
## Open a Pull Request
6280

63-
Once you have implemented your feature or fixed a bug push it to your fork and start a Pull Request.
81+
Once you have implemented your feature or fixed a bug push it to your fork and
82+
start a Pull Request.
6483

6584
## Merge Upstream Changes
6685

67-
Occasionally you will want to merge changes in the upstream repository (the official code repo) with your fork.
86+
Occasionally you will want to merge changes in the upstream repository (the
87+
official code repo) with your fork.
6888

69-
```
89+
```shell
7090
cd path/to/nodecg-io
7191
git checkout master
7292
git pull https://github.com/codeoverflow-org/nodecg-io master
7393
```
7494

7595
Manage any merge conflicts, commit them, and then push them to your fork.
7696

77-
You may also occasionally need to merge upstream master in a pull request. To do that make the above to update your local master, and then merge your local master into your PR branch.
97+
You may also occasionally need to merge upstream master in a pull request. To do
98+
that make the above to update your local master, and then merge your local
99+
master into your PR branch.
78100

79101
### Where to Contribute
80102

81-
After cloning and building the repo, check out the [issues list](https://github.com/codeoverflow-org/nodecg-io/issues). Issues labelled [`help wanted`](https://github.com/codeoverflow-org/nodecg-io/labels/help%20wanted) are good issues to submit a PR for. Issues labelled [`good first issue`](https://github.com/codeoverflow-org/nodecg-io/labels/good%20first%20issue) are great candidates to pick up if you are in the code for the first time. If you are contributing significant changes, please discuss with the assignee of the issue first before starting to work on the issue.
103+
After cloning and building the repo, check out the
104+
[issues list](https://github.com/codeoverflow-org/nodecg-io/issues). Issues
105+
labelled
106+
[help wanted](https://github.com/codeoverflow-org/nodecg-io/labels/help%20wanted)
107+
are good issues to submit a PR for. Issues labelled
108+
[good first issue](https://github.com/codeoverflow-org/nodecg-io/labels/good%20first%20issue)
109+
are great candidates to pick up if you are in the code for the first time. If
110+
you are contributing significant changes, please discuss with the assignee of
111+
the issue first before starting to work on the issue. You may also contribute to
112+
this [documentation](docs_setup.md).
82113

83114
## Suggestions
84115

85-
We're also interested in your feedback. You can submit a suggestion or feature request through the issue tracker. To make this process more effective, we're asking that these include more information to help define them more clearly.
116+
We're also interested in your feedback. You can submit a suggestion or feature
117+
request through the issue tracker. To make this process more effective, we're
118+
asking that these include more information to help define them more clearly.
86119

87120
## Discussion Etiquette
88121

89-
In order to keep the conversation clear and transparent, please limit discussion to English and keep things on topic with the issue. Be considerate to others and try to be courteous and professional at all times.
122+
In order to keep the conversation clear and transparent, please limit discussion
123+
to English and keep things on topic with the issue. Be considerate to others and
124+
try to be courteous and professional at all times.

‎docs/contribute/create_sample.md

Lines changed: 67 additions & 57 deletions
Original file line numberDiff line numberDiff line change
@@ -1,75 +1,85 @@
11
# Create a sample bundle
22

3-
A sample should have the same name as the service, but it may include a short description in the name after the service name as well.
4-
E.g. `twitch-chat` or `obs-scenelist`.
3+
A sample should have the same name as the service, but it may include a short
4+
description in the name after the service name as well. E.g. `twitch-chat` or
5+
`obs-scenelist`.
56

6-
Create a folder in `samples` named after the sample and add a `package.json` and a `tsconfig.json`:
7+
Create a folder in `samples` named after the sample and add a `package.json` and
8+
a `tsconfig.json`:
79

8-
`package.json`
10+
=== "package.json"
911

10-
```json
11-
{
12-
"name": "<the sample name>",
13-
"private": true,
14-
"version": "0.2.0",
15-
"nodecg": {
16-
"compatibleRange": "^1.1.1",
17-
"bundleDependencies": {
18-
"nodecg-io-<the service name>": "^0.2.0"
12+
```json
13+
{
14+
"name": "<the sample name>",
15+
"private": true,
16+
"version": "0.2.0",
17+
"nodecg": {
18+
"compatibleRange": "^1.1.1",
19+
"bundleDependencies": {
20+
"nodecg-io-<the service name>": "^0.2.0"
21+
}
22+
},
23+
"scripts": {
24+
"build": "tsc -b",
25+
"watch": "tsc -b -w",
26+
"clean": "tsc -b --clean"
27+
},
28+
"license": "MIT",
29+
"dependencies": {
30+
"nodecg-io-<the service name>": "^0.2.0",
31+
"nodecg-io-core": "^0.2.0",
32+
"@types/node": "^15.0.2",
33+
"nodecg-types": "^1.8.2",
34+
"typescript": "^4.2.4"
1935
}
20-
},
21-
"scripts": {
22-
"build": "tsc -b",
23-
"watch": "tsc -b -w",
24-
"clean": "tsc -b --clean"
25-
},
26-
"license": "MIT",
27-
"dependencies": {
28-
"nodecg-io-<the service name>": "^0.2.0",
29-
"nodecg-io-core": "^0.2.0",
30-
"@types/node": "^15.0.2",
31-
"nodecg-types": "^1.8.2",
32-
"typescript": "^4.2.4"
3336
}
34-
}
35-
```
37+
```
3638

37-
`tsconfig.json`
39+
=== "tsconfig.json"
3840

39-
```json
40-
{
41-
"extends": "../../tsconfig.common.json",
42-
"references": [
43-
{
44-
"path": "../../nodecg-io-core"
45-
},
46-
{
47-
"path": "../../services/nodecg-io-<the service name>"
48-
}
49-
]
50-
}
51-
```
41+
```json
42+
{
43+
"extends": "../../tsconfig.common.json",
44+
"references": [
45+
{
46+
"path": "../../nodecg-io-core"
47+
},
48+
{
49+
"path": "../../services/nodecg-io-<the service name>"
50+
}
51+
]
52+
}
53+
```
54+
55+
Now you can create a file called `extension/index.ts`. Here's a template. Make
56+
sure you replace all the comments with your own code.
5257

53-
Now you can create a file called `extension/index.ts`. Here's a template. Make sure you replace all the comments with your own code.
58+
=== "index.ts"
5459

55-
```typescript
56-
import { NodeCG } from "nodecg-types/types/server";
57-
import { requireService } from "nodecg-io-core";
58-
import { TheServicesExportedClient } from "nodecg-io-<the services name>";
60+
```typescript
61+
import { NodeCG } from "nodecg-types/types/server";
62+
import { requireService } from "nodecg-io-core";
63+
import { TheServicesExportedClient } from "nodecg-io-<the services name>";
5964

60-
module.exports = function (nodecg: NodeCG) {
61-
nodecg.log.info("Sample bundle for <the-service-name> started");
65+
module.exports = function (nodecg: NodeCG) {
66+
nodecg.log.info("Sample bundle for <the-service-name> started");
6267

63-
const service = requireService<TheServicesExportedClient>(nodecg, "<the-service-name>");
64-
service?.onAvailable((client) => {
65-
nodecg.log.info("<the-service-name> client has been updated.");
68+
const service = requireService<TheServicesExportedClient>(
69+
nodecg,
70+
"<the-service-name>"
71+
);
72+
service?.onAvailable((client) => {
73+
nodecg.log.info("<the-service-name> client has been updated.");
6674

67-
// TODO do something with the client to demonstrate the functionality.
68-
});
75+
// TODO do something with the client to demonstrate the functionality.
76+
});
6977

70-
service?.onUnavailable(() => nodecg.log.info("<the-service-name> client has been unset."));
71-
};
72-
```
78+
service?.onUnavailable(() =>
79+
nodecg.log.info("<the-service-name> client has been unset.")
80+
);
81+
};
82+
```
7383

7484
## Next steps
7585

0 commit comments

Comments
 (0)