docs: adds the initial documentation site (#14)

Co-authored-by: Andrew Frantz <[email protected]>
Co-authored-by: Andrew Thrasher <[email protected]>

.github/workflows/CI.yml

@@ -1,4 +1,4 @@
-name: CI
+name: Rust CI
 
 on: 
   push:

.github/workflows/docs.yml

@@ -0,0 +1,47 @@
+name: Project Docs
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "latest"
+      - run: cd docs && npm install && npm run docs:build
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          name: "Project Documentation"
+          path: "docs/.vitepress/dist"
+  deploy:
+    needs: build
+    if: success() && github.ref == 'refs/heads/main'
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
+        with:
+          artifact_name: "Project Documentation"

README.md

@@ -20,7 +20,7 @@
   </p>
 
   <p align="center">
-    A package manager for Workflow Description Language files.
+    A bioinformatics workflow orchestration engine and package manager built on top of the Workflow Description Language (WDL).
     <br />
     <br />
     <a href="https://github.com/stjude-rust-labs/sprocket/issues/new?assignees=&title=Descriptive%20Title&labels=enhancement">Request Feature</a>
@@ -41,18 +41,25 @@
 
 ## Guiding Principles
 
-* **Modern, reliable foundation for everyday bioinformatics analysis—written in Rust.** `sprocket` aims to package together a fairly comprehensive set of tools and for developing bioinformatics tasks and workflows using the [Workflow Description Language](http://openwdl.org/). It is built with modern, multi-core systems in mind and written in Rust.
-* **WDL specification focused.** We aim to implement the various versions of the [OpenWDL specification](https://github.com/openwdl/wdl) to the letter. In other words, `sprocket` aims to be workflow engine independent. In the future, we plan to make `sprocket` extendable for workflow engine teams.
+* Provide a **high-performance** workflow execution engine capable of
+  orchestrating massive bioinformatics workloads (the stated target is 20,000+
+  concurrent jobs).
+* Develop a suite of **modern development tools** that brings bioinformatics
+  development on par with other modern languages (e.g.,
+  [`wdl-lsp`](https://github.com/stjude-rust-labs/wdl/tree/main/wdl-lsp)).
+* Maintain an **community-focused codebase** that enables a diverse set of
+  contributors from academic, non-profit, and commercial organizations.
+* Build on an **open, domain-tailored standard** to ensure the toolset remains
+  singularly focused on unencumbered innovation within bioinformatics.
+* Retain a **simple and accessible user experience** when complexity isn't warranted.
+  warranted.
 
 ## 📚 Getting Started
 
 ### Installation
 
 Before you can install `sprocket`, you'll need to install
-[Rust](https://www.rust-lang.org/). We recommend using
-[rustup](https://rustup.rs/) to accomplish this.
-
-Once Rust is installed, you can install the latest version of `sprocket` by
+[Rust](https://www.rust-lang.org/). We recommend using [rustup](https://rustup.rs/) to accomplish this. Once Rust is installed, you can install the latest version of `sprocket` by
 running the following command.
 
 ```bash

docs/.gitignore

@@ -0,0 +1,11 @@
+*.log
+*.tgz
+.DS_Store
+.idea
+.temp
+.vite_opt_cache
+.vscode
+dist
+cache
+node_modules
+pnpm-global

docs/.vitepress/config.mts

@@ -0,0 +1,41 @@
+import { defineConfig } from 'vitepress'
+
+export default defineConfig({
+  title: "Sprocket",
+  description: "A bioinformatics workflow orchestration engine and package manager built on top of the Workflow Description Language (WDL)",
+  themeConfig: {
+    nav: [
+      { text: 'Documentation', link: '/overview' },
+      {
+        text: "v0.5.0",
+        items: [
+          {
+            text: 'Changelog',
+            link: 'https://github.com/stjude-rust-labs/sprocket/blob/main/CHANGELOG.md'
+          }
+        ]
+      }
+    ],
+
+    sidebar: [
+      {
+        text: 'Getting Started',
+        items: [
+          { text: 'Overview', link: '/overview' },
+          { text: 'Installation', link: '/installation' },
+        ]
+      },
+      {
+        text: 'Visual Studio Code Extension',
+        items: [
+          { text: 'Getting Started', link: '/vscode/getting-started' },
+        ]
+      }
+    ],
+
+
+    socialLinks: [
+      { icon: 'github', link: 'https://github.com/stjude-rust-labs/sprocket' }
+    ]
+  }
+})

docs/.vitepress/theme/Layout.vue

@@ -0,0 +1,21 @@
+<script setup lang="ts">
+import { useData } from 'vitepress'
+
+// https://vitepress.dev/reference/runtime-api#usedata
+const { site, frontmatter } = useData()
+</script>
+
+<template>
+  <div v-if="frontmatter.home">
+    <h1>{{ site.title }}</h1>
+    <p>{{ site.description }}</p>
+    <ul>
+      <li><a href="/overview.html">Overview</a></li>
+      <li><a href="/installation.html">Installation</a></li>
+    </ul>
+  </div>
+  <div v-else>
+    <a href="/">Home</a>
+    <Content />
+  </div>
+</template>

docs/.vitepress/theme/index.ts

@@ -0,0 +1,17 @@
+// https://vitepress.dev/guide/custom-theme
+import { h } from 'vue'
+import type { Theme } from 'vitepress'
+import DefaultTheme from 'vitepress/theme'
+import './style.css'
+
+export default {
+  extends: DefaultTheme,
+  Layout: () => {
+    return h(DefaultTheme.Layout, null, {
+      // https://vitepress.dev/guide/extending-default-theme#layout-slots
+    })
+  },
+  enhanceApp({ app, router, siteData }) {
+    // ...
+  }
+} satisfies Theme

docs/.vitepress/theme/style.css

@@ -0,0 +1,138 @@
+/**
+ * Customize default theme styling by overriding CSS variables:
+ * https://github.com/vuejs/vitepress/blob/main/src/client/theme-default/styles/vars.css
+ */
+
+/**
+ * Colors
+ *
+ * Each colors have exact same color scale system with 3 levels of solid
+ * colors with different brightness, and 1 soft color.
+ *
+ * - `XXX-1`: The most solid color used mainly for colored text. It must
+ *   satisfy the contrast ratio against when used on top of `XXX-soft`.
+ *
+ * - `XXX-2`: The color used mainly for hover state of the button.
+ *
+ * - `XXX-3`: The color for solid background, such as bg color of the button.
+ *   It must satisfy the contrast ratio with pure white (#ffffff) text on
+ *   top of it.
+ *
+ * - `XXX-soft`: The color used for subtle background such as custom container
+ *   or badges. It must satisfy the contrast ratio when putting `XXX-1` colors
+ *   on top of it.
+ *
+ *   The soft color must be semi transparent alpha channel. This is crucial
+ *   because it allows adding multiple "soft" colors on top of each other
+ *   to create a accent, such as when having inline code block inside
+ *   custom containers.
+ *
+ * - `default`: The color used purely for subtle indication without any
+ *   special meanings attched to it such as bg color for menu hover state.
+ *
+ * - `brand`: Used for primary brand colors, such as link text, button with
+ *   brand theme, etc.
+ *
+ * - `tip`: Used to indicate useful information. The default theme uses the
+ *   brand color for this by default.
+ *
+ * - `warning`: Used to indicate warning to the users. Used in custom
+ *   container, badges, etc.
+ *
+ * - `danger`: Used to show error, or dangerous message to the users. Used
+ *   in custom container, badges, etc.
+ * -------------------------------------------------------------------------- */
+
+ :root {
+  --vp-c-default-1: var(--vp-c-gray-1);
+  --vp-c-default-2: var(--vp-c-gray-2);
+  --vp-c-default-3: var(--vp-c-gray-3);
+  --vp-c-default-soft: var(--vp-c-gray-soft);
+
+  --vp-c-brand-1: var(--vp-c-indigo-1);
+  --vp-c-brand-2: var(--vp-c-indigo-2);
+  --vp-c-brand-3: var(--vp-c-indigo-3);
+  --vp-c-brand-soft: var(--vp-c-indigo-soft);
+
+  --vp-c-tip-1: var(--vp-c-brand-1);
+  --vp-c-tip-2: var(--vp-c-brand-2);
+  --vp-c-tip-3: var(--vp-c-brand-3);
+  --vp-c-tip-soft: var(--vp-c-brand-soft);
+
+  --vp-c-warning-1: var(--vp-c-yellow-1);
+  --vp-c-warning-2: var(--vp-c-yellow-2);
+  --vp-c-warning-3: var(--vp-c-yellow-3);
+  --vp-c-warning-soft: var(--vp-c-yellow-soft);
+
+  --vp-c-danger-1: var(--vp-c-red-1);
+  --vp-c-danger-2: var(--vp-c-red-2);
+  --vp-c-danger-3: var(--vp-c-red-3);
+  --vp-c-danger-soft: var(--vp-c-red-soft);
+}
+
+/**
+ * Component: Button
+ * -------------------------------------------------------------------------- */
+
+:root {
+  --vp-button-brand-border: transparent;
+  --vp-button-brand-text: var(--vp-c-white);
+  --vp-button-brand-bg: var(--vp-c-brand-3);
+  --vp-button-brand-hover-border: transparent;
+  --vp-button-brand-hover-text: var(--vp-c-white);
+  --vp-button-brand-hover-bg: var(--vp-c-brand-2);
+  --vp-button-brand-active-border: transparent;
+  --vp-button-brand-active-text: var(--vp-c-white);
+  --vp-button-brand-active-bg: var(--vp-c-brand-1);
+}
+
+/**
+ * Component: Home
+ * -------------------------------------------------------------------------- */
+
+:root {
+  --vp-home-hero-name-color: transparent;
+  --vp-home-hero-name-background: -webkit-linear-gradient(
+    120deg,
+    #bd34fe 30%,
+    #41d1ff
+  );
+
+  --vp-home-hero-image-background-image: linear-gradient(
+    -45deg,
+    #bd34fe 50%,
+    #47caff 50%
+  );
+  --vp-home-hero-image-filter: blur(44px);
+}
+
+@media (min-width: 640px) {
+  :root {
+    --vp-home-hero-image-filter: blur(56px);
+  }
+}
+
+@media (min-width: 960px) {
+  :root {
+    --vp-home-hero-image-filter: blur(68px);
+  }
+}
+
+/**
+ * Component: Custom Block
+ * -------------------------------------------------------------------------- */
+
+:root {
+  --vp-custom-block-tip-border: transparent;
+  --vp-custom-block-tip-text: var(--vp-c-text-1);
+  --vp-custom-block-tip-bg: var(--vp-c-brand-soft);
+  --vp-custom-block-tip-code-bg: var(--vp-c-brand-soft);
+}
+
+/**
+ * Component: Algolia
+ * -------------------------------------------------------------------------- */
+
+.DocSearch {
+  --docsearch-primary-color: var(--vp-c-brand-1) !important;
+}

docs/index.md

@@ -0,0 +1,14 @@
+---
+layout: home
+
+hero:
+  name: "Sprocket"
+  text: "A bioinformatics workflow orchestration engine and package manager"
+  actions:
+    - theme: brand
+      text: Install Sprocket
+      link: /installation
+    - theme: alt
+      text: Overview
+      link: /overview
+---

docs/installation.md

@@ -0,0 +1,52 @@
+# Installation
+
+If you're looking for the latest stable version of the `sprocket` command line
+tool, you can download it from any of the [package managers](#package-managers)
+listed below. Otherwise, see the [build from source](#build-from-source) section
+on how to obtain and build a copy of the source code.
+
+## Package Managers
+
+### Homebrew
+
+::: warning Notice
+While we'd like to make `sprocket` easily installable via [Homebrew], we're
+waiting to surpass the [75 star
+requirement](https://docs.brew.sh/Acceptable-Formulae#niche-or-self-submitted-stuff)
+for Homebrew formulas. If you feel so inclined, help us get there by starring [the
+repo](https://github.com/stjude-rust-labs/sprocket)!
+:::
+
+### Crates.io
+
+Before you can build `sprocket`, you'll need to install [Rust]. We recommend
+using [rustup] to accomplish this. Once Rust is installed, you can install the
+latest version of `sprocket` by running the following command.
+
+::: code-group
+
+```shell
+cargo install sprocket
+```
+
+:::
+
+This will pull in the latest published version on [crates.io].
+
+
+## Build From Source
+
+Both the source code and the instructions to build the `sprocket` command line
+tool are available on GitHub at
+[`stjude-rust-labs/sprocket`](https://github.com/stjude-rust-labs/sprocket).
+
+* The [releases](https://github.com/stjude-rust-labs/sprocket/releases) page
+  contains all of the official releases for the project.
+* If desired, you can install either the latest unpublished version (the code
+  available on `main`) _or_ any experimental features by checking out the
+  associated feature branch (`git checkout <branch-name>`).
+
+[Homebrew]: https://brew.sh/
+[Rust]: https://rust-lang.org/
+[rustup]: https://rustup.rs/
+[crates.io]: https://crates.io/crates/sprocket