Serve docs folder and API reference on GitHub pages (cursorless-dev#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]>

.github/workflows/deploy-docs.yml

@@ -0,0 +1,36 @@
+name: Deploy docs
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: production
+    steps:
+      - uses: actions/checkout@v2
+        with:
+          token: ${{ secrets.CURSORLESS_BOT_TOKEN }}
+      - name: Configure GPG Key
+        run: |
+          echo -n "$GPG_SIGNING_KEY" | base64 --decode | gpg --import
+        env:
+          GPG_SIGNING_KEY: ${{ secrets.CURSORLESS_BOT_GPG_SIGNING_KEY }}
+      - name: git config
+        run: |
+          git config user.name cursorless-bot
+          git config user.email [email protected]
+          git config user.signingkey A9387720AFC62221
+          git config commit.gpgsign true
+      - uses: actions/setup-node@v2
+        with:
+          node-version: 16
+          cache: yarn
+      - run: ./scripts/docs-build.sh
+      - name: Deploy
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          personal_token: ${{ secrets.CURSORLESS_BOT_TOKEN }}
+          publish_dir: ./gh-pages-root/

.github/workflows/test-docs.yml

@@ -0,0 +1,22 @@
+name: Test docs
+
+on:
+  pull_request:
+    branches: main
+    types: [opened, synchronize, reopened]
+
+jobs:
+  test-docs-build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: actions/setup-node@v2
+        with:
+          node-version: 16
+          cache: yarn
+      - run: ./scripts/docs-build.sh
+  markdown-link-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@master
+      - uses: gaurav-nelson/github-action-markdown-link-check@v1

.gitignore

@@ -4,3 +4,10 @@ node_modules
 .vscode-test/
 *.vsix
 package-lock.json
+*.DS_Store
+
+# TypeDoc output
+docs/contributing/api/
+
+# Generated docs hub
+gh-pages-root/docs/

.vscode/launch.json

@@ -61,6 +61,14 @@
 				"${workspaceFolder}/out/test/**/*.js"
 			],
 			"preLaunchTask": "${defaultBuildTask}"
-		}
+		},
+		{
+            "name": "Docusaurus Start (Debug)",
+            "type": "node",
+            "request": "launch",
+            "cwd": "${workspaceFolder}/website",
+            "runtimeExecutable": "npm",
+            "runtimeArgs": ["run", "start"],
+        }
 	]
 }

CHANGELOG.md

@@ -1,3 +1,5 @@
+<!-- markdown-link-check-disable -->
+
 # Change Log
 
 All notable changes to the "cursorless" extension will be documented in this file.

CONTRIBUTING.md

@@ -1,55 +1,4 @@
 # Contributing
 
-### Installation
-
-```sh
-yarn install
-```
-
-### Running tests
-
-```sh
-yarn run test
-```
-
-### Adding tests
-
-See [test-case-recorder.md](docs/contributing/test-case-recorder.md).
-
-### Adding a new programming language
-
-See [docs](docs/contributing/adding-a-new-language.md).
-
-### Adding syntactic scope types to an existing language
-
-See [parse-tree-patterns.md](docs/contributing/parse-tree-patterns.md).
-
-### Changing SVGs
-
-#### SVG preprocessing script
-
-You'll probably want to run the following to make sure the SVGs have everything they need:
-
-```sh
-yarn run compile && node ./out/scripts/preprocessSvgHats.js
-```
-
-This script will add dummy width, height and fill attributes as necessary to appease the regex in `Decorations.ts`
-
-#### Adding hat adjustments at finish
-
-While tweaking, the easiest approach is probably to use the
-`cursorless.individualHatAdjustments` setting in your settings.json to change
-size / alignment so you don't need to refresh every time. Once you're done, you
-can paste the settings into `scripts/hatAdjustments/add.ts` and run the following to get
-your updates:
-
-```sh
-yarn run compile && node ./out/scripts/hatAdjustments/add.js
-```
-
-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:
-
-```sh
-yarn run compile && node ./out/scripts/hatAdjustments/average.js
-```
+Please see the [contributing section](https://www.cursorless.org/docs/contributing)
+of the documentation hub.

docs/contributing/CONTRIBUTING.md

@@ -0,0 +1,55 @@
+# Contributing
+
+### Installation
+
+```sh
+yarn install
+```
+
+### Running tests
+
+```sh
+yarn run test
+```
+
+### Adding tests
+
+See [test-case-recorder.md](./test-case-recorder.md).
+
+### Adding a new programming language
+
+See [docs](./adding-a-new-language.md).
+
+### Adding syntactic scope types to an existing language
+
+See [parse-tree-patterns.md](./parse-tree-patterns.md).
+
+### Changing SVGs
+
+#### SVG preprocessing script
+
+You'll probably want to run the following to make sure the SVGs have everything they need:
+
+```sh
+yarn run compile && node ./out/scripts/preprocessSvgHats.js
+```
+
+This script will add dummy width, height and fill attributes as necessary to appease the regex in `Decorations.ts`
+
+#### Adding hat adjustments at finish
+
+While tweaking, the easiest approach is probably to use the
+`cursorless.individualHatAdjustments` setting in your settings.json to change
+size / alignment so you don't need to refresh every time. Once you're done, you
+can paste the settings into `scripts/hatAdjustments/add.ts` and run the following to get
+your updates:
+
+```sh
+yarn run compile && node ./out/scripts/hatAdjustments/add.js
+```
+
+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:
+
+```sh
+yarn run compile && node ./out/scripts/hatAdjustments/average.js
+```

docs/contributing/_api-index.md

@@ -0,0 +1,5 @@
+# Cursorless internals
+
+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.
+
+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

@@ -13,7 +13,7 @@ for how to add support for a new parser
 
 First a few notes / tips:
 
-- 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.
+- 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.
 - 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 😇
 
 Minimum changes that each language needs:

docs/contributing/parse-tree-patterns.md

@@ -8,13 +8,13 @@ We have a small domain-specific language that we use to define patterns to look
 
 | Syntax              | Description                                                                                                                     |
 | ------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
-| TYPE                | Match node type<br>`node.type`                                                                                                  |
+| TYPE                | Match node type<br/>`node.type`                                                                                                  |
 | Dot operator(`.`)   | Type hierarchy between parent and child                                                                                         |
 | Wildcard op(`*`)    | Match any type                                                                                                                  |
 | Negation op(`~`)    | Match any type other than what is specified after `~`                                                                           |
-| Important op(`!`)   | Use this node as result instead of parent.<br>By default the leftmost/top node is used                                          |
+| Important op(`!`)   | Use this node as result instead of parent.<br/>By default the leftmost/top node is used                                          |
 | Optional op(`?`)    | Node is optional. Will match if available.                                                                                      |
-| Field op(`[field]`) | Get child field node for resulting node.<br>Only evaluated on the resulting node at the end.<br>`node.childForFieldName(field)` |
+| Field op(`[field]`) | Get child field node for resulting node.<br/>Only evaluated on the resulting node at the end.<br/>`node.childForFieldName(field)` |
 
 ## Multiple patterns
 

docs/user/README.md

@@ -1,3 +1,7 @@
+---
+slug: /
+---
+
 # Cursorless documentation
 
 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

@@ -0,0 +1 @@
+www.cursorless.org

gh-pages-root/index.html

@@ -0,0 +1,6 @@
+<!doctype html>
+<html class="docs-version-current" lang="en" dir="ltr">
+<head>
+<meta charset="UTF-8">
+<meta http-equiv="refresh" content="0; url=./docs" />
+</head>

package.json

@@ -524,12 +524,12 @@
 		"npm-license-crawler": "^0.2.1",
 		"semver": "^7.3.5",
 		"sinon": "^11.1.1",
-		"typescript": "^4.4.4",
+		"typescript": "^4.5.5",
 		"vscode-test": "^1.4.1"
 	},
 	"dependencies": {
 		"@types/lodash": "^4.14.168",
 		"immutability-helper": "^3.1.1",
 		"lodash": "^4.17.21"
 	}
-}
+}

scripts/docs-build.sh

@@ -0,0 +1,17 @@
+#!/bin/sh
+
+# We still need the main project to have all depedencies
+# it will be compiled as part of API docs generation
+yarn install --frozen-lockfile
+
+cd website
+yarn install --frozen-lockfile
+yarn build
+cd ..
+
+# Since baseUrl in Docusaurus is /docs, for links within our website
+# to work correctly we need to serve /gh-pages-root with /docs subfolder
+# containting the build
+rm -rf gh-pages-root/docs
+mkdir -p gh-pages-root/docs
+cp -r website/build/* gh-pages-root/docs

src/core/Decorations.ts

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

src/core/commandRunner/CommandRunner.ts

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

src/core/inferFullTargets.ts

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

src/extension.ts

@@ -7,6 +7,14 @@ import { getCommandServerApi, getParseTreeApi } from "./util/getExtensionApi";
 import isTesting from "./testUtil/isTesting";
 import CommandRunner from "./core/commandRunner/CommandRunner";
 
+/**
+ * Extension entrypoint called by VSCode on Cursorless startup.
+ * - Creates a dependency container {@link Graph} with the components that
+ * implement Cursorless.
+ * - Creates test case recorder {@link TestCaseRecorder} for contributors to
+ * use to record test cases.
+ * - Creates an entrypoint for running commands {@link CommandRunner}.
+ */
 export async function activate(context: vscode.ExtensionContext) {
   const { getNodeAtLocation } = await getParseTreeApi();
   const commandServerApi = await getCommandServerApi();

src/processTargets/index.ts

@@ -13,6 +13,20 @@ import processModifier from "./modifiers/processModifier";
 import processPosition from "./processPosition";
 import processSelectionType from "./processSelectionType";
 
+/**
+ * Converts the abstract target descriptions provided by the user to a concrete
+ * representation usable by actions. Conceptually, the input will be something
+ * like "the function call argument containing the cursor" and the output will be something
+ * like "line 3, characters 5 through 10".
+ * @param context Captures the environment needed to convert the abstract target
+ *    description given by the user to a concrete representation usable by
+ *    actions
+ * @param targets The abstract target representations provided by the user
+ * @returns A list of lists of typed selections, one list per input target. Each
+ * typed selection includes the selection, as well the uri of the document
+ * containing it, and potentially rich context information such as how to remove
+ * the target
+ */
 export default function (
   context: ProcessedTargetsContext,
   targets: Target[]