Minor Cursorless docs follow-up tweaks (#610)

* Have a bit more exposition and point to API doc landing page on contributing landing page.
Fixes #609

* Test broken link

* Fail on docs build fail

* Remove broken link

* Various stuff

* Remove unnecessary markdown link checker

* Fix link

* More docs cleanup

* Tweak deploy setup

.github/workflows/deploy-docs.yml

@@ -11,26 +11,15 @@ jobs:
     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 98099035+cursorless-bot@users.noreply.github.com
-          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
+      - run: bash -x scripts/docs-build.sh
       - name: Deploy
         uses: peaceiris/actions-gh-pages@v3
         with:
           personal_token: ${{ secrets.CURSORLESS_BOT_TOKEN }}
           publish_dir: ./gh-pages-root/
+          user_name: "cursorless-bot"
+          user_email: "98099035+cursorless-bot@users.noreply.github.com"

.github/workflows/test-docs.yml

@@ -14,9 +14,4 @@ jobs:
         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
+      - run: bash -x scripts/docs-build.sh

docs/contributing/CONTRIBUTING.md

@@ -1,16 +1,27 @@
 # Contributing
 
+Welcome! So glad you've decided to help make Cursorless better. Once you've
+learned how to [install](#installation) and [run / test a local copy of the
+extension](#running--testing-extension-locally), you may want to check out the
+[API docs](api) to learn more about how Cursorless works.
+
 ### Installation
 
 ```sh
-yarn install
+yarn
 ```
 
-### Running tests
+### Running / testing extension locally
 
-```sh
-yarn run test
-```
+In order to test out your local version of the extension or to run unit tests
+locally you need to run the extension in debug mode. To do so you need to run
+the `workbench.action.debug.selectandstart` command and then select either "Run
+Extension" or "Extension Tests".
+
+### Running docs site locally
+
+Run the `workbench.action.debug.selectandstart` command and then select
+"Docusaurus Start (Debug)".
 
 ### Adding tests
 

docs/contributing/_api-index.md

@@ -1,5 +1,10 @@
 # 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.
+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).
+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](classes/core_commandRunner_CommandRunner.CommandRunner#runcommand).

scripts/docs-build.sh

@@ -1,4 +1,4 @@
-#!/bin/sh
+set -euo pipefail
 
 # We still need the main project to have all depedencies
 # it will be compiled as part of API docs generation

website/docusaurus.config.js

@@ -94,6 +94,9 @@ const config = {
             remarkPluginFixLinksToRepositoryArtifacts,
           ],
         },
+        theme: {
+          customCss: [require.resolve("./src/css/custom.css")],
+        },
       }),
     ],
   ],
@@ -124,6 +127,12 @@ const config = {
             sidebarId: "contributing",
             label: "For contributors",
           },
+          {
+            href: "https://github.com/cursorless-dev/cursorless-vscode",
+            position: "right",
+            className: "header-github-link",
+            "aria-label": "GitHub repository",
+          },
         ],
       },
       prism: {

website/src/css/custom.css

@@ -0,0 +1,18 @@
+/* From https://github.com/facebook/docusaurus/blob/cc0bceab9c1678303f6237f5526753edc1b12fc3/website/src/css/custom.css#L70-L86 */
+.header-github-link:hover {
+  opacity: 0.6;
+}
+
+.header-github-link::before {
+  content: "";
+  width: 24px;
+  height: 24px;
+  display: flex;
+  background: url("data:image/svg+xml,%3Csvg viewBox='0 0 24 24' xmlns='http://www.w3.org/2000/svg'%3E%3Cpath d='M12 .297c-6.63 0-12 5.373-12 12 0 5.303 3.438 9.8 8.205 11.385.6.113.82-.258.82-.577 0-.285-.01-1.04-.015-2.04-3.338.724-4.042-1.61-4.042-1.61C4.422 18.07 3.633 17.7 3.633 17.7c-1.087-.744.084-.729.084-.729 1.205.084 1.838 1.236 1.838 1.236 1.07 1.835 2.809 1.305 3.495.998.108-.776.417-1.305.76-1.605-2.665-.3-5.466-1.332-5.466-5.93 0-1.31.465-2.38 1.235-3.22-.135-.303-.54-1.523.105-3.176 0 0 1.005-.322 3.3 1.23.96-.267 1.98-.399 3-.405 1.02.006 2.04.138 3 .405 2.28-1.552 3.285-1.23 3.285-1.23.645 1.653.24 2.873.12 3.176.765.84 1.23 1.91 1.23 3.22 0 4.61-2.805 5.625-5.475 5.92.42.36.81 1.096.81 2.22 0 1.606-.015 2.896-.015 3.286 0 .315.21.69.825.57C20.565 22.092 24 17.592 24 12.297c0-6.627-5.373-12-12-12'/%3E%3C/svg%3E")
+    no-repeat;
+}
+
+[data-theme="dark"] .header-github-link::before {
+  background: url("data:image/svg+xml,%3Csvg viewBox='0 0 24 24' xmlns='http://www.w3.org/2000/svg'%3E%3Cpath fill='white' d='M12 .297c-6.63 0-12 5.373-12 12 0 5.303 3.438 9.8 8.205 11.385.6.113.82-.258.82-.577 0-.285-.01-1.04-.015-2.04-3.338.724-4.042-1.61-4.042-1.61C4.422 18.07 3.633 17.7 3.633 17.7c-1.087-.744.084-.729.084-.729 1.205.084 1.838 1.236 1.838 1.236 1.07 1.835 2.809 1.305 3.495.998.108-.776.417-1.305.76-1.605-2.665-.3-5.466-1.332-5.466-5.93 0-1.31.465-2.38 1.235-3.22-.135-.303-.54-1.523.105-3.176 0 0 1.005-.322 3.3 1.23.96-.267 1.98-.399 3-.405 1.02.006 2.04.138 3 .405 2.28-1.552 3.285-1.23 3.285-1.23.645 1.653.24 2.873.12 3.176.765.84 1.23 1.91 1.23 3.22 0 4.61-2.805 5.625-5.475 5.92.42.36.81 1.096.81 2.22 0 1.606-.015 2.896-.015 3.286 0 .315.21.69.825.57C20.565 22.092 24 17.592 24 12.297c0-6.627-5.373-12-12-12'/%3E%3C/svg%3E")
+    no-repeat;
+}