Skip to content

Commit d90a369

Browse files
bra1nDumppokey
bra1nDump
and
pokey
authored
Serve docs folder and API reference on GitHub pages (#477)
* Inline documentation added for some key functions * Docusaurus minimal set up added * Fixed links to repository sub directories * Added contributing/api using TypeDoc * Updated publish docs workflow * Link hack docs, publish only on main branch * Update website/docusaurus.config.js More robust fixing relative link to repository artifacts Co-authored-by: Pokey Rule <[email protected]> * Addressed review comments; Github workflow to test documentation build added * Update .github/workflows/deploy-docs.yml Co-authored-by: Pokey Rule <[email protected]> * Update .github/workflows/deploy-docs.yml Deployment should be authored by cursor less bot Co-authored-by: Pokey Rule <[email protected]> * Apply pull request suggestion * missing-exports plugging added * Moved contributing; Added new API index page * Avoid copying docs folder * Fix links to GitHub after docs folder move in previous commit * Fixed issue were relative links were rewritten to point to GitHub * Add stub contributing * Fix broken link to svg calculations * Add broken markdown link checker * Update tagline and run dock sours can fig through prettier * Disable markdown link checking in CHANGELOG.md * Factored out typedoc configuration from docusaurus * Prevents broken links like https://.../../ generated * Fixed link giving warning * Fixed typo * Better docusaurus config documentation * Serve folder with /docs/ subdir <- website/build for baseUrl to work correctly * Added CNAME to gh-pages root. Otherwise adhock commits when updated from GitHub Pages UI * Cleanup docs * Docs * More docs * Update docs-build.sh to clean out old artifacts Co-authored-by: Pokey Rule <[email protected]> * runCommand fixed list numbering * Hide API index from the sidebar * Bumped docusaurus dependencies, minor nice improvements * Moved dogs build script to scripts folder * Edit launch configuration to debug docusaurus configuration * Use `www` as default * Switch to www * Fix ci * Trigger notification Co-authored-by: Pokey Rule <[email protected]>
1 parent 16dc10e commit d90a369

33 files changed

+11892
-284
lines changed

‎.github/workflows/deploy-docs.yml

+36
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
name: Deploy docs
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
8+
jobs:
9+
publish:
10+
runs-on: ubuntu-latest
11+
environment: production
12+
steps:
13+
- uses: actions/checkout@v2
14+
with:
15+
token: ${{ secrets.CURSORLESS_BOT_TOKEN }}
16+
- name: Configure GPG Key
17+
run: |
18+
echo -n "$GPG_SIGNING_KEY" | base64 --decode | gpg --import
19+
env:
20+
GPG_SIGNING_KEY: ${{ secrets.CURSORLESS_BOT_GPG_SIGNING_KEY }}
21+
- name: git config
22+
run: |
23+
git config user.name cursorless-bot
24+
git config user.email [email protected]
25+
git config user.signingkey A9387720AFC62221
26+
git config commit.gpgsign true
27+
- uses: actions/setup-node@v2
28+
with:
29+
node-version: 16
30+
cache: yarn
31+
- run: ./scripts/docs-build.sh
32+
- name: Deploy
33+
uses: peaceiris/actions-gh-pages@v3
34+
with:
35+
personal_token: ${{ secrets.CURSORLESS_BOT_TOKEN }}
36+
publish_dir: ./gh-pages-root/

‎.github/workflows/test-docs.yml

+22
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
name: Test docs
2+
3+
on:
4+
pull_request:
5+
branches: main
6+
types: [opened, synchronize, reopened]
7+
8+
jobs:
9+
test-docs-build:
10+
runs-on: ubuntu-latest
11+
steps:
12+
- uses: actions/checkout@v2
13+
- uses: actions/setup-node@v2
14+
with:
15+
node-version: 16
16+
cache: yarn
17+
- run: ./scripts/docs-build.sh
18+
markdown-link-check:
19+
runs-on: ubuntu-latest
20+
steps:
21+
- uses: actions/checkout@master
22+
- uses: gaurav-nelson/github-action-markdown-link-check@v1

‎.gitignore

+7
Original file line numberDiff line numberDiff line change
@@ -4,3 +4,10 @@ node_modules
44
.vscode-test/
55
*.vsix
66
package-lock.json
7+
*.DS_Store
8+
9+
# TypeDoc output
10+
docs/contributing/api/
11+
12+
# Generated docs hub
13+
gh-pages-root/docs/

‎.vscode/launch.json

+9-1
Original file line numberDiff line numberDiff line change
@@ -61,6 +61,14 @@
6161
"${workspaceFolder}/out/test/**/*.js"
6262
],
6363
"preLaunchTask": "${defaultBuildTask}"
64-
}
64+
},
65+
{
66+
"name": "Docusaurus Start (Debug)",
67+
"type": "node",
68+
"request": "launch",
69+
"cwd": "${workspaceFolder}/website",
70+
"runtimeExecutable": "npm",
71+
"runtimeArgs": ["run", "start"],
72+
}
6573
]
6674
}

‎CHANGELOG.md

+2
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
<!-- markdown-link-check-disable -->
2+
13
# Change Log
24

35
All notable changes to the "cursorless" extension will be documented in this file.

‎CONTRIBUTING.md

+2-53
Original file line numberDiff line numberDiff line change
@@ -1,55 +1,4 @@
11
# Contributing
22

3-
### Installation
4-
5-
```sh
6-
yarn install
7-
```
8-
9-
### Running tests
10-
11-
```sh
12-
yarn run test
13-
```
14-
15-
### Adding tests
16-
17-
See [test-case-recorder.md](docs/contributing/test-case-recorder.md).
18-
19-
### Adding a new programming language
20-
21-
See [docs](docs/contributing/adding-a-new-language.md).
22-
23-
### Adding syntactic scope types to an existing language
24-
25-
See [parse-tree-patterns.md](docs/contributing/parse-tree-patterns.md).
26-
27-
### Changing SVGs
28-
29-
#### SVG preprocessing script
30-
31-
You'll probably want to run the following to make sure the SVGs have everything they need:
32-
33-
```sh
34-
yarn run compile && node ./out/scripts/preprocessSvgHats.js
35-
```
36-
37-
This script will add dummy width, height and fill attributes as necessary to appease the regex in `Decorations.ts`
38-
39-
#### Adding hat adjustments at finish
40-
41-
While tweaking, the easiest approach is probably to use the
42-
`cursorless.individualHatAdjustments` setting in your settings.json to change
43-
size / alignment so you don't need to refresh every time. Once you're done, you
44-
can paste the settings into `scripts/hatAdjustments/add.ts` and run the following to get
45-
your updates:
46-
47-
```sh
48-
yarn run compile && node ./out/scripts/hatAdjustments/add.js
49-
```
50-
51-
If instead, you want to average your adjustments with those in main and see the differences to get to yours and main, you can paste the settings into `scripts/hatAdjustments/average.ts` and run:
52-
53-
```sh
54-
yarn run compile && node ./out/scripts/hatAdjustments/average.js
55-
```
3+
Please see the [contributing section](https://www.cursorless.org/docs/contributing)
4+
of the documentation hub.

‎docs/contributing/CONTRIBUTING.md

+55
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
# Contributing
2+
3+
### Installation
4+
5+
```sh
6+
yarn install
7+
```
8+
9+
### Running tests
10+
11+
```sh
12+
yarn run test
13+
```
14+
15+
### Adding tests
16+
17+
See [test-case-recorder.md](./test-case-recorder.md).
18+
19+
### Adding a new programming language
20+
21+
See [docs](./adding-a-new-language.md).
22+
23+
### Adding syntactic scope types to an existing language
24+
25+
See [parse-tree-patterns.md](./parse-tree-patterns.md).
26+
27+
### Changing SVGs
28+
29+
#### SVG preprocessing script
30+
31+
You'll probably want to run the following to make sure the SVGs have everything they need:
32+
33+
```sh
34+
yarn run compile && node ./out/scripts/preprocessSvgHats.js
35+
```
36+
37+
This script will add dummy width, height and fill attributes as necessary to appease the regex in `Decorations.ts`
38+
39+
#### Adding hat adjustments at finish
40+
41+
While tweaking, the easiest approach is probably to use the
42+
`cursorless.individualHatAdjustments` setting in your settings.json to change
43+
size / alignment so you don't need to refresh every time. Once you're done, you
44+
can paste the settings into `scripts/hatAdjustments/add.ts` and run the following to get
45+
your updates:
46+
47+
```sh
48+
yarn run compile && node ./out/scripts/hatAdjustments/add.js
49+
```
50+
51+
If instead, you want to average your adjustments with those in main and see the differences to get to yours and main, you can paste the settings into `scripts/hatAdjustments/average.ts` and run:
52+
53+
```sh
54+
yarn run compile && node ./out/scripts/hatAdjustments/average.js
55+
```

‎docs/contributing/_api-index.md

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# Cursorless internals
2+
3+
This document is intended to present a high-level overview of the Cursorless architecture, as well as key pointers to locations in the code base to help contributors get up to speed.
4+
5+
For the time being, we recommend watching the [internals walk-through videos](https://youtube.com/playlist?list=PLkafpFOBVedScHi0dy_80DsHwnZIOSOTy) and having a look through the API docs, starting from the [`runCommand` function](https://www.cursorless.org/docs/contributing/api/classes/core_commandRunner_CommandRunner.CommandRunner#runcommand).

‎docs/contributing/adding-a-new-language.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ for how to add support for a new parser
1313

1414
First a few notes / tips:
1515

16-
- We suggest opening a draft PR as soon as possible to get early feedback. Please use the new language PR template either by adding `?template=new_programming_language` to the end of the URL you used to open the PR, or just by copying and pasting from the [template](../../.github/PULL_REQUEST_TEMPLATE/new_programming_language.md) to your PR body, if that's easier.
16+
- We suggest opening a draft PR as soon as possible to get early feedback. Please use the new language PR template either by adding `?template=new_programming_language` to the end of the URL you used to open the PR, or just by copying and pasting from the [template](https://github.com/cursorless-dev/cursorless-vscode/tree/main/.github/PULL_REQUEST_TEMPLATE/new_programming_language.md) to your PR body, if that's easier.
1717
- We suggest adding tests as early as possible, after each language feature you add. Recording tests is quick and painless using the test case recorder described below. We promise 😇
1818

1919
Minimum changes that each language needs:

‎docs/contributing/parse-tree-patterns.md

+3-3
Original file line numberDiff line numberDiff line change
@@ -8,13 +8,13 @@ We have a small domain-specific language that we use to define patterns to look
88

99
| Syntax | Description |
1010
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
11-
| TYPE | Match node type<br>`node.type` |
11+
| TYPE | Match node type<br/>`node.type` |
1212
| Dot operator(`.`) | Type hierarchy between parent and child |
1313
| Wildcard op(`*`) | Match any type |
1414
| Negation op(`~`) | Match any type other than what is specified after `~` |
15-
| Important op(`!`) | Use this node as result instead of parent.<br>By default the leftmost/top node is used |
15+
| Important op(`!`) | Use this node as result instead of parent.<br/>By default the leftmost/top node is used |
1616
| Optional op(`?`) | Node is optional. Will match if available. |
17-
| Field op(`[field]`) | Get child field node for resulting node.<br>Only evaluated on the resulting node at the end.<br>`node.childForFieldName(field)` |
17+
| Field op(`[field]`) | Get child field node for resulting node.<br/>Only evaluated on the resulting node at the end.<br/>`node.childForFieldName(field)` |
1818

1919
## Multiple patterns
2020

‎docs/user/README.md

+4
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,7 @@
1+
---
2+
slug: /
3+
---
4+
15
# Cursorless documentation
26

37
Welcome to Cursorless! You may find it helpful to start with the [tutorial video](https://www.youtube.com/watch?v=JxcNW0hnfTk).

‎gh-pages-root/CNAME

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
www.cursorless.org

‎gh-pages-root/index.html

+6
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
<!doctype html>
2+
<html class="docs-version-current" lang="en" dir="ltr">
3+
<head>
4+
<meta charset="UTF-8">
5+
<meta http-equiv="refresh" content="0; url=./docs" />
6+
</head>

‎package.json

+2-2
Original file line numberDiff line numberDiff line change
@@ -524,12 +524,12 @@
524524
"npm-license-crawler": "^0.2.1",
525525
"semver": "^7.3.5",
526526
"sinon": "^11.1.1",
527-
"typescript": "^4.4.4",
527+
"typescript": "^4.5.5",
528528
"vscode-test": "^1.4.1"
529529
},
530530
"dependencies": {
531531
"@types/lodash": "^4.14.168",
532532
"immutability-helper": "^3.1.1",
533533
"lodash": "^4.17.21"
534534
}
535-
}
535+
}

‎scripts/docs-build.sh

+17
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
#!/bin/sh
2+
3+
# We still need the main project to have all depedencies
4+
# it will be compiled as part of API docs generation
5+
yarn install --frozen-lockfile
6+
7+
cd website
8+
yarn install --frozen-lockfile
9+
yarn build
10+
cd ..
11+
12+
# Since baseUrl in Docusaurus is /docs, for links within our website
13+
# to work correctly we need to serve /gh-pages-root with /docs subfolder
14+
# containting the build
15+
rm -rf gh-pages-root/docs
16+
mkdir -p gh-pages-root/docs
17+
cp -r website/build/* gh-pages-root/docs

‎src/core/Decorations.ts

+1-1
Original file line numberDiff line numberDiff line change
@@ -240,7 +240,7 @@ export default class Decorations {
240240
/**
241241
* Creates an SVG from the hat SVG that pads, offsets and scales it to end up
242242
* in the right size / place relative to the character it will be placed over.
243-
* [This image](../images/svg-calculations.png) may or may not be helpful.
243+
* [This image](../../images/svg-calculations.png) may or may not be helpful.
244244
*
245245
* @param fontMeasurements Info about the user's font
246246
* @param shape The hat shape to process

‎src/core/commandRunner/CommandRunner.ts

+23
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,29 @@ export default class CommandRunner {
3535
);
3636
}
3737

38+
/**
39+
* Entry point for Cursorless commands. We proceed as follows:
40+
*
41+
* 1. Canonicalize the action name and target representation using
42+
* {@link canonicalizeAndValidateCommand}, primarily for the purpose of
43+
* backwards compatibility
44+
* 2. Perform inference on targets to fill in details left out using things
45+
* like previous targets and action preferences. For example we would
46+
* automatically infer that `"take funk air and bat"` is equivalent to
47+
* `"take funk air and funk bat"`. See {@link inferFullTargets} for details
48+
* of how this is done.
49+
* 3. Construct a {@link ProcessedTargetsContext} object to capture the
50+
* environment needed by {@link processTargets}.
51+
* 4. Call {@link processTargets} to map each abstract {@link Target} object
52+
* to a concrete list of {@link TypedSelection} objects.
53+
* 5. Run the requested action on the given selections. The mapping from
54+
* action id (eg `remove`) to implementation is defined in
55+
* {@link Actions}. To understand how actions work, see some examples,
56+
* such as `"take"` {@link SetSelection} and `"chuck"` {@link Delete}. See
57+
* 6. Update `source` and `that` marks, if they have been returned from the
58+
* action, and returns the desired return value indicated by the action, if
59+
* it has one.
60+
*/
3861
async runCommand(commandArgument: CommandArgument) {
3962
try {
4063
if (this.graph.debug.active) {

‎src/core/inferFullTargets.ts

+11-1
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,17 @@ import {
99
PartialListTarget,
1010
} from "../typings/Types";
1111

12-
export default function (
12+
/**
13+
* Performs inference on the partial targets provided by the user, using
14+
* previous targets, global defaults, and action-specific defaults to fill out
15+
* any details that may have been omitted in the spoken form.
16+
* For example, we would automatically infer that `"take funk air and bat"` is
17+
* equivalent to `"take funk air and funk bat"`.
18+
* @param targets The partial targets which need to be completed by inference.
19+
* @param actionPreferences The preferences provided by the action, so that different actions can provide their own defaults
20+
* @returns Target objects fully filled out and ready to be processed by {@link processTargets}.
21+
*/
22+
export default function inferFullTargets(
1323
targets: PartialTarget[],
1424
actionPreferences: ActionPreferences[]
1525
): Target[] {

‎src/extension.ts

+8
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,14 @@ import { getCommandServerApi, getParseTreeApi } from "./util/getExtensionApi";
77
import isTesting from "./testUtil/isTesting";
88
import CommandRunner from "./core/commandRunner/CommandRunner";
99

10+
/**
11+
* Extension entrypoint called by VSCode on Cursorless startup.
12+
* - Creates a dependency container {@link Graph} with the components that
13+
* implement Cursorless.
14+
* - Creates test case recorder {@link TestCaseRecorder} for contributors to
15+
* use to record test cases.
16+
* - Creates an entrypoint for running commands {@link CommandRunner}.
17+
*/
1018
export async function activate(context: vscode.ExtensionContext) {
1119
const { getNodeAtLocation } = await getParseTreeApi();
1220
const commandServerApi = await getCommandServerApi();

‎src/processTargets/index.ts

+14
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,20 @@ import processModifier from "./modifiers/processModifier";
1313
import processPosition from "./processPosition";
1414
import processSelectionType from "./processSelectionType";
1515

16+
/**
17+
* Converts the abstract target descriptions provided by the user to a concrete
18+
* representation usable by actions. Conceptually, the input will be something
19+
* like "the function call argument containing the cursor" and the output will be something
20+
* like "line 3, characters 5 through 10".
21+
* @param context Captures the environment needed to convert the abstract target
22+
* description given by the user to a concrete representation usable by
23+
* actions
24+
* @param targets The abstract target representations provided by the user
25+
* @returns A list of lists of typed selections, one list per input target. Each
26+
* typed selection includes the selection, as well the uri of the document
27+
* containing it, and potentially rich context information such as how to remove
28+
* the target
29+
*/
1630
export default function (
1731
context: ProcessedTargetsContext,
1832
targets: Target[]

0 commit comments

Comments
 (0)