Skip to content

Commit 0e3b58a

Browse files
ethankhallethankhall
authored
Update to use Docusaurus for website (#29)
1 parent 008c1e6 commit 0e3b58a

37 files changed

+8993
-215
lines changed

‎.github/bin/build-page.sh

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
#!/usr/bin/env bash
2+
3+
SCRIPT_DIR=$( cd -- "$( dirname -- "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )
4+
5+
docker run -v "${SCRIPT_DIR}/../../docs:/app/docs" --entrypoint sh --workdir /app/docs node:20-buster build.sh

‎.github/workflows/gh-page.yml

+7-6
Original file line numberDiff line numberDiff line change
@@ -16,17 +16,18 @@ jobs:
1616
steps:
1717
- uses: actions/checkout@v3
1818

19-
- name: Setup mdBook
20-
uses: peaceiris/actions-mdbook@v1
21-
with:
22-
mdbook-version: 'latest'
19+
- run: .github/bin/build-page.sh
2320

24-
- run: mdbook build docs
21+
- name: Fix permissions
22+
run: |
23+
chmod -c -R +rX "docs/build/" | while read line; do
24+
echo "::warning title=Invalid file permissions automatically fixed::$line"
25+
done
2526
2627
- name: Publish to pages
2728
uses: actions/upload-pages-artifact@v3
2829
with:
29-
path: docs/book
30+
path: docs/build
3031
deploy:
3132
# Add a dependency to the build job
3233
needs: build

‎docs/.gitignore

+20-1
Original file line numberDiff line numberDiff line change
@@ -1 +1,20 @@
1-
book
1+
# Dependencies
2+
/node_modules
3+
4+
# Production
5+
/build
6+
7+
# Generated files
8+
.docusaurus
9+
.cache-loader
10+
11+
# Misc
12+
.DS_Store
13+
.env.local
14+
.env.development.local
15+
.env.test.local
16+
.env.production.local
17+
18+
npm-debug.log*
19+
yarn-debug.log*
20+
yarn-error.log*

‎docs/README.md

+41
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
# Website
2+
3+
This website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator.
4+
5+
### Installation
6+
7+
```
8+
$ yarn
9+
```
10+
11+
### Local Development
12+
13+
```
14+
$ yarn start
15+
```
16+
17+
This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
18+
19+
### Build
20+
21+
```
22+
$ yarn build
23+
```
24+
25+
This command generates static content into the `build` directory and can be served using any static contents hosting service.
26+
27+
### Deployment
28+
29+
Using SSH:
30+
31+
```
32+
$ USE_SSH=true yarn deploy
33+
```
34+
35+
Not using SSH:
36+
37+
```
38+
$ GIT_USER=<Your GitHub username> yarn deploy
39+
```
40+
41+
If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.

‎docs/babel.config.js

+3
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
module.exports = {
2+
presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
3+
};

‎docs/book.toml

-6
This file was deleted.

‎docs/build.sh

+6
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
#!/usr/bin/env bash
2+
3+
set -eux
4+
5+
yarn install
6+
yarn build

‎docs/docs/commands/analyze/analyze-logs.md

+9
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
---
2+
sidebar_position: 1
3+
---
4+
5+
# Analyze Logs
6+
7+
`scope analyze logs` allows the user to provide a log file, or stdin. The file is parsed, and matches against the [ScopeKnownError](../../models/ScopeKnownError.md)'s.
8+
9+
Once all the known errors are matched, the search will stop.

‎docs/docs/commands/analyze/index.md

+11
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
---
2+
sidebar_position: 1
3+
---
4+
5+
# Analyze
6+
7+
Analyze an environment.
8+
9+
## Sub Commands
10+
11+
- [logs](analyze-logs.md) - Parse logs from stdin or a file.

‎docs/docs/commands/doctor.md

+44
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
---
2+
sidebar_position: 1
3+
---
4+
5+
# Doctor
6+
7+
Doctor is used to fix a local environment. To fix a machine, you'll need to provide either [ScopeDoctorCheck](../models/ScopeDoctorCheck.md) or [ScopeDoctorSetup](../models/ScopeDoctorSetup.md) files. Multiple are supported and recommended.
8+
9+
**Help Text**
10+
11+
```text
12+
Run checks that will "checkup" your machine
13+
14+
Usage: scope doctor [OPTIONS] <COMMAND>
15+
16+
Commands:
17+
run Run checks against your machine, generating support output
18+
list List all doctor config, giving you the ability to know what is possible
19+
help Print this message or the help of the given subcommand(s)
20+
```
21+
22+
## `run`
23+
24+
`scope doctor run` is used to execute all the doctor steps. All checks will be run, if you want to only run specific checks, the `--only` flag with the name of the check to run. This option can be provided multiple times.
25+
26+
By default, any provided fix's will be run. If you don't want to run fixes add `--fix=false` to disable fixing issues.
27+
28+
When using a [ScopeDoctorSetup](../models/ScopeDoctorSetup.md), the checksum of files are stored on disk. If you need to disable caching, add `--no-cache`.
29+
30+
```text
31+
Run checks against your machine, generating support output
32+
33+
Usage: scope doctor run [OPTIONS]
34+
35+
Options:
36+
-o, --only <ONLY> When set, only the checks listed will run
37+
-f, --fix <FIX> When set, if a fix is specified it will also run [default: true] [possible values: true, false]
38+
-n, --no-cache When set cache will be disabled, forcing all file based checks to run
39+
(excluded default args)
40+
```
41+
42+
## `list`
43+
44+
Will print out all doctor checks available.

‎docs/docs/commands/index.md

+33
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
---
2+
sidebar_position: 2
3+
---
4+
5+
# Commands
6+
7+
`scope` has several built-in commands that most engineers will use:
8+
- [`doctor`](doctor.md) - Run checks that will "checkup" your machine
9+
- [`report`](report.md) - Generate a bug report based from a command
10+
- [`analyze`](analyze/index.md) - Analyze configuration and print validation messages
11+
12+
Beyond the built-in command, scope will also run any binary prefixed with `scope-`.
13+
14+
Additionally, there is `list` that will output all the found configuration.
15+
16+
Here is an example output of `scope list` run from the `examples/` directory.
17+
18+
```text
19+
17:47:57 INFO Commands
20+
17:47:57 INFO Name Description
21+
17:47:57 INFO --------------------------------------------------------------------------------
22+
17:47:57 INFO bar External sub-command, run `scope bar` for help
23+
17:47:57 INFO doctor Run checks that will "checkup" your machine
24+
17:47:57 INFO foo External sub-command, run `scope foo` for help
25+
17:47:57 INFO list List the found config files, and resources detected
26+
17:47:57 INFO report Generate a bug report based from a command that was ran
27+
```
28+
29+
Under the `Commands` section, notice two additional commands:
30+
- `bar` which is located in `.scope/bin/scope-bar`
31+
- `foo` which is a binary on the `PATH`
32+
33+
Scope automatically adds `.scope/bin` to the path when searching. Allowing teams to add commands to scope in large repos. For example, in a mono-repo with multiple services, you may want to add a `deploy` command. The `deploy` command would come from the working dir.

‎docs/src/report/intercept.md ‎docs/docs/commands/intercept.md

+4
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,7 @@
1+
---
2+
sidebar_position: 3
3+
---
4+
15
# Scope Intercept
26

37
Reporting bugs after the fact is useful, but if the tool can determine that there was an error and prompt the user to report a bug is better. Scope Intercept is an `env` "replacement" that can be used in [shebang](https://en.wikipedia.org/wiki/Shebang_(Unix)) in scripts.

‎docs/docs/commands/report.md

+20
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
---
2+
sidebar_position: 2
3+
---
4+
5+
# Report
6+
7+
`scope report` is used to generate a bug report.
8+
9+
To build a bug report, two different files are used:
10+
11+
- [ScopeReportDefinition](../models/ScopeReportDefinition.md) - is used to define what to include in the bug report. There can only be one report definition at one time.
12+
- [ScopeReportLocation](../models/ScopeReportLocation.md) - defines where to upload reports to.
13+
14+
When reporting a bug, scope will auto redact well known keys and patterns to reduce sharing private information.
15+
16+
The output from the command will be captured and uploaded.
17+
18+
## Special Thanks
19+
20+
We took our redaction string from [sirwart/ripsecrets](https://github.com/sirwart/ripsecrets).

‎docs/docs/intro.md

+53
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
---
2+
sidebar_position: 1
3+
---
4+
5+
# Scope
6+
7+
Scope allows teams to define development config for engineers. Scope is a tool for engineers, to make them more productive.
8+
9+
The config falls into three major categories:
10+
- [Local setup](./commands/doctor.md)
11+
- [Error debugging locally](models/ScopeKnownError.md)
12+
- [Generate great bug reports](./commands/report.md)
13+
14+
## Config
15+
16+
Configuration for `scope` is done via Kubernetes-like yaml files that live inside the repo. By default, scope will search up for the config directory `.scope` and ready `*.yaml` and `*.yml` files.
17+
18+
That means `.scope/foo.yaml` will be parsed as a config file, but `scope/foo.yaml` will not (notice the missing `.` before `scope`).
19+
20+
A config file looks like
21+
22+
```yaml
23+
apiVersion: scope.github.com/v1alpha
24+
kind: <kind>
25+
metadata:
26+
name: a useful name
27+
spec:
28+
...
29+
```
30+
31+
Currently, the only supported `apiVersion` is `scope.github.com/v1alpha`. Using `apiVersion` allows scope to evolve the config file and keep older versions of the config compatible.
32+
33+
Unlike Kubernetes, the `name` field can be any string, without any DNS related constraints.
34+
35+
## CLI Options
36+
All commands support the following options
37+
38+
```text
39+
Usage: scope [OPTIONS] <COMMAND>
40+
41+
Options:
42+
-d, --debug... A level of verbosity, and can be used multiple times
43+
-w, --warn Enable warn logging
44+
-e, --error Disable everything but error logging
45+
--extra-config <EXTRA_CONFIG> Add a paths to search for configuration. By default, `scope` will search up for `.scope` directories and attempt to load `.yml` and `.yaml` files for config. If the config directory is somewhere else, specifying this option will _add_ the paths/files to the loaded config [env: SCOPE_CONFIG_DIR=]
46+
--disable-default-config When set, default config files will not be loaded and only specified config will be loaded [env: SCOPE_DISABLE_DEFAULT_CONFIG=]
47+
-C, --working-dir <WORKING_DIR> Override the working directory
48+
--run-id <RUN_ID> When outputting logs, or other files, the run-id is the unique value that will define where these go. In the case that the run-id is re-used, the old values will be overwritten [env: SCOPE_RUN_ID=]
49+
-h, --help Print help (see more with '--help')
50+
-V, --version Print version
51+
```
52+
53+
Normally, you will not need to set any of these files.

‎docs/src/doctor/doctor-check.md ‎docs/docs/models/ScopeDoctorCheck.md

+6-3
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,8 @@
1-
# Doctor Check
1+
---
2+
sidebar_position: 2
3+
---
24

3-
Check instructions are used to verity the environment has dependencies working, usually things like a database or dependent services.
5+
# ScopeDoctorCheck
46

57
Looking at `doctor-check-path-exists.yaml` in the example folder.
68

@@ -10,6 +12,7 @@ kind: ScopeDoctorCheck
1012
metadata:
1113
name: path-exists
1214
spec:
15+
# order: 100 # default value
1316
check:
1417
target: scripts/does-path-env-exist.sh
1518
fix:
@@ -22,7 +25,7 @@ The kind is `ScopeDoctorCheck`, letting scope know that this is a Check instruct
2225

2326
## Schema
2427

25-
- `.spec.check.target` is a script to run, used to check if the system is working. If the script exits 0, that indicates success. Otherwise, that something is wrong. The scripts are relative to the folder containing spec file. If this file was at `$HOME/workspace/example/.scope/check.yaml` the command to run would be `$HOME/workspace/example/.scope/scripts/does-path-env-exist.sh`
28+
- `.spec.check.target` is a script to run, used to check if the system is working. If the script exits 0, that indicates success. Otherwise, that something is wrong. The scripts are relative to the folder containing spec file. If this file was at `$HOME/workspace/example/.scope/check.yaml` the command to run would be `$HOME/workspace/example/.scope/scripts/does-path-env-exist.sh`
2629

2730
- `.spec.fix.target` is an optional command to run when the check fails. If provided, the fix will automatically run.
2831

‎docs/src/doctor/doctor-setup.md ‎docs/docs/models/ScopeDoctorSetup.md

+4-4
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
1-
# Doctor Setup
1+
---
2+
sidebar_position: 1
3+
---
24

3-
Setup instructions are used to install dependencies, run db migrations, and other changes based on files present in the repo. These instructions will most often be run after a `git pull` or other similar step.
4-
5-
Looking at `doctor-setup.yaml` in the examples repo
5+
# ScopeDoctorSetup
66

77
```yaml
88
apiVersion: scope.github.com/v1alpha

‎docs/src/errors/known-error.md ‎docs/docs/models/ScopeKnownError.md

+6-6
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,8 @@
1-
# Known Errors
1+
---
2+
sidebar_position: 3
3+
---
24

3-
A Known Error, provides a way for repo owners to describe errors that others may run into, and how to fix them.
4-
5-
A known error is only used when using the `intercept` binary.
6-
7-
Looking at `known-error.yaml` in the examples directory.
5+
# ScopeKnownError
86

97
```yaml
108
apiVersion: scope.github.com/v1alpha
@@ -17,5 +15,7 @@ spec:
1715
help: The command had an error, try reading the logs around there to find out what happened.
1816
```
1917
18+
## Schema
19+
2020
- `.spec.pattern` is a Regex that will be run over stdout and stderr to search for a known error.
2121
- `.spec.help` is the description given when the pattern matches

0 commit comments

Comments
 (0)