docs: reworks README.md to be more friendly for the extensions browser

stjude-rust-labs · Aug 9, 2024 · 295f100 · 295f100
1 parent b283adc
commit 295f100
Showing 1 changed file with 84 additions and 48 deletions.
diff --git a/README.md b/README.md
@@ -1,8 +1,89 @@
-# Sprocket VS Code Extension
+<p align="center">
+  <h1 align="center">
+  Sprocket VS Code Extension
+  </h1>
+
+  <p align="center">
+    <a href="https://github.com/stjude-rust-labs/sprocket-vscode/blob/main/LICENSE-APACHE" target="_blank">
+      <img alt="License: Apache 2.0" src="https://img.shields.io/badge/license-Apache 2.0-blue.svg" />
+    </a>
+    <a href="https://github.com/stjude-rust-labs/sprocket-vscode/blob/main/LICENSE-MIT" target="_blank">
+      <img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-blue.svg" />
+    </a>
+    <br/>
+    <a href="https://github.com/stjude-rust-labs/sprocket-vscode/issues/new?assignees=&labels=&template=feature_request.md&title=Descriptive%20Title&labels=enhancement"><strong>Request Feature »</strong></a>
+    ·
+    <a href="https://github.com/stjude-rust-labs/sprocket-vscode/issues/new?assignees=&labels=&template=bug_report.md&title=Descriptive%20Title&labels=bug"><strong>Report Bug »</strong></a>
+    <br />
+  </p>
+</p>
+
+## Overview
+
+This extension provides support for the <a href="https://openwdl.org/">Workflow
+Description Language</a>. Generally speaking, it does this by interacting with the
+[`sprocket`](https://github.com/stjude-rust-labs/sprocket) command line tool (and,
+behind the scenes, the [`wdl`](https://github.com/stjude-rust-labs/wdl) family of
+crates), though some functionality lives only within this extension.
+
+## Getting Started
+
+As this is an early version of both `sprocket` and this extension, you are required to
+install `sprocket` yourself and make it available on the `PATH` (future versions of
+this extension will automatically install and manage the `sprocket` binary for you).
+
+You can do so by running the following commands:
 
-This Visual Studio Code extension provides support for the [Workflow Description Language](https://openwdl.org/).
+```bash
+# (1) Ensure Rust is installed by following the instructions at https://rustup.rs.
+
+# (2) Install the latest version of `sprocket`.
+cargo install --git https://github.com/stjude-rust-labs/sprocket
+
+# (3) Make sure `sprocket` is accesible from the command line.
+sprocket --version
+```
+
+You should now be set! Alternatively, a path to the `sprocket` binary can be provided in the extension
+by setting the `sprocket.server.path` configuration option.
+
+## 🎨 Features
 
-## Prerequisites
+* **Basic syntax highlighting** using a complete and up-to-date [TextMate
+  grammar](https://macromates.com/manual/en/language_grammars). _This grammar is slated
+  to drive GitHub's syntax highlighting for WDL files [in a future
+  release](https://github.com/github-linguist/linguist/pull/6972)_.
+* **Document and workspace diagnostics** courtesy of the language server protocol
+  implementation provided by`sprocket analyzer`.
+* **Code snippets** for common WDL constructs and conventions.
+
+_**Note:** more features will be added as `sprocket` is developed. Please check out the
+activity on the [Sprocket repository](https://github.com/stjude-rust-labs/sprocket) to
+see what we're working on next!_
+
+## Known Issues
+
+- The extension is in an early stage of development and may not work as
+  expected.
+- The extension requires a separate installation of the `sprocket` command line
+  tool; in the future, the extension will automatically install the tool.
+- When `sprocket` unexpectedly terminates, the extension does not automatically
+  restart it and you must manually restart the extension host to recover from
+  the error; this will change in the future as the extension becomes more
+  stable.
+
+## Configuration
+
+The extension provides the following configuration options:
+
+- `sprocket.server.path`: The path to the `sprocket` command line tool. By
+  default, the extension assumes that `sprocket` is on your PATH.
+- `sprocket.server.verbose`: Passes the `--verbose` flag to `sprocket` when
+  running it.
+- `sprocket.server.lint`: Passes the `--lint` flag to `sprocket` when running
+  it; this enables additional linting checks that are not enabled by default.
+
+## Development
 
 ### Setup
 
@@ -40,29 +121,6 @@ yarn compile
 This command will automatically be run when you start the extension in the
 development environment or when packaging the extension.
 
-### Running
-
-To run the extension, you must have the `sprocket` command line tool installed
-on your PATH.
-
-To install `sprocket`, ensure you a [Rust Toolchain](https://rustup.rs/)
-installed.
-
-With Rust installed, you can install `sprocket` using the following command:
-
-```bash
-cargo install --git https://github.com/stjude-rust-labs/sprocket
-```
-
-Alternatively, a path to the `sprocket` binary can be provided in the extension
-by setting the `sprocket.server.path` configuration option.
-
-## Features
-
-- Syntax highlighting
-- Document and workspace diagnostics
-
-**_More features will be added in the future._**
 
 ## Running The Development Extension
 
@@ -87,25 +145,3 @@ vsce package --yarn
 ```
 
 This will generate a `sprocket-vscode-<version>.vsix` file that you can install in VS Code using the `Extensions: install from VSIX` command.
-
-# Known Issues
-
-- The extension is in an early stage of development and may not work as
-  expected.
-- The extension requires a separate installation of the `sprocket` command line
-  tool; in the future, the extension will automatically install the tool.
-- When `sprocket` unexpectedly terminates, the extension does not automatically
-  restart it and you must manually restart the extension host to recover from
-  the error; this will change in the future as the extension becomes more
-  stable.
-
-# Configuration
-
-The extension provides the following configuration options:
-
-- `sprocket.server.path`: The path to the `sprocket` command line tool. By
-  default, the extension assumes that `sprocket` is on your PATH.
-- `sprocket.server.verbose`: Passes the `--verbose` flag to `sprocket` when
-  running it.
-- `sprocket.server.lint`: Passes the `--lint` flag to `sprocket` when running
-  it; this enables additional linting checks that are not enabled by default.