Documentation for the Mephisto Review CLI and front-end build work (#612

)

* Add review CLI docs

* Add more content

* Add Contributos & Authors folder

* Docs reorg

* Update broken link

* fix sidebar

* Position quickstart at the top of the Guides sidebar

* Sidebar and footer updates

* Flesh out sidebar organization a bit more

docs/web/docs/development.md → docs/web/docs/contributors/development.md

@@ -9,7 +9,7 @@ To setup your local codebase to auto-lint and avoid lint test failures for your
 3. `pre-commit run --all-files` (optional - run ad-hoc against all files)
 
 
-# Front-end Development (new)
+## Package Development (new)
 *For commits after the `yarn-pkg-reorg` tag and for newer packages (`@annotated/*`)*
 
 This repo uses yarn workspaces to manage it's front-end dependencies.
@@ -77,7 +77,7 @@ $ yarn build-all
     More information on the flags for `foreach` can be found [here](https://yarnpkg.com/cli/workspaces/foreach).
 
 
-# Front-end Development (old)
+## Package Development (old)
 
 *For commits before the `yarn-pkg-reorg` tag or for non-workspace packages, e.g. `global-context-store`, `annotation-toolkit`, `bootstrap-chat`.*
 

docs/web/docs/guides/how-tos/_category_.yml

@@ -0,0 +1,2 @@
+label: "How-Tos"
+collapsed: false

docs/web/docs/quickstart.md → docs/web/docs/guides/quickstart.md

@@ -1,3 +1,7 @@
+---
+sidebar_position: 1
+---
+
 # 10-minute Quickstart
 
 First, clone this repo to your local system.

docs/web/docs/reference/overview.md

@@ -0,0 +1,14 @@
+# Overview
+
+This section of the documentation will soon be auto-generated.
+
+In the meanwhile, you may find reference documentation in the following locations:
+
+- [`mephisto-task`](https://github.com/facebookresearch/Mephisto/tree/main/packages/mephisto-task) - This package provides two hooks to faciliate React-based front-end development for Mephisto tasks. Use `useMephistoTask` for simple, static tasks or `useMephistoLiveTask` for multi-turn, socket-based tasks.
+- [`bootstrap-chat`](https://github.com/facebookresearch/Mephisto/tree/main/packages/bootstrap-chat)A set of UI components based on Bootstrap v3 for facilitating chat-based tasks for Mephisto.
+- [`annotation-toolkit` and `@annotated`](https://github.com/facebookresearch/Mephisto/tree/main/packages/annotation-toolkit) - This package helps users to build out review & annotation tooling for their research tasks. `annotation-toolkit` has been deprecated in favor of `@annotated`.
+- [`cra-template-mephisto-review`](https://github.com/facebookresearch/Mephisto/tree/main/packages/cra-template-mephisto-review) - A customizable base template for creating data exploration interfaces with first-class support for the `mephisto review` command.
+- [`mephisto-review-hook`](https://github.com/facebookresearch/Mephisto/tree/main/packages/mephisto-review-hook) - TODO
+
+
+

docs/web/docs/tutorials/review-cli.md

@@ -0,0 +1,53 @@
+# Using the Mephisto Review CLI
+
+Once you've [installed Mephisto](../quickstart), you have access to the `mephisto` command line utility.
+
+This utility can be used to invoke a review workflow via `$ mephisto review ...`.
+
+## Overview
+
+To review data, you must specify:
+
+1. The actual data to review
+2. The visual interface to represent the data
+3. If approving/rejecting (as opposed to  exploring), what to do with the results
+
+Here's a sample command:
+
+```shell
+cat input.jsonl | mephisto review --json my-review-interface --stdout
+```
+
+Here we:
+
+1. Pipe in the contents of `input.jsonl` to the `mephisto review` command. This is our review data as newline separated JSON objects. (*We also specify the `--json` flag to indicate that this is JSON input as opposed to the default CSV.*)
+
+2. Point to the build location of our review interface. This is a single-page app that implements the `useMephistoReview()` hook to consume data. (*To start with a starter template, you can you `cra-template-mephisto-review`. We will elaborate on this below.*)
+
+3. Specify the output of our approve/reject data. For now we will just print it out to standard output with the `--stdout` flag.
+
+## 1. Use the starter template
+
+The quickest way to create your own review interface is to use the `cra-template-mephisto-review` template with `create-react-app`:
+
+```
+npx create-react-app --template mephisto-review my-review-interface
+```
+
+Once setup, you can build, and test the template:
+
+```shell
+$ cd my-review-interface
+$ yarn build
+$ cat sample-data.jsonl | mephisto review --json --stdout build/
+```
+
+*Note: The template ships with some sample data files: `sample-data.jsonl` and `sample-data.csv`*
+
+## 2. Create a custom renderer
+
+TODO
+
+## 3. Create custom thumbnails
+
+TODO

docs/web/docusaurus.config.js

@@ -51,9 +51,21 @@ const config = {
         items: [
           {
             type: "doc",
-            docId: "quickstart",
+            docId: "guides/quickstart",
             position: "left",
-            label: "Tutorial",
+            label: "Guides",
+          },
+          {
+            type: "doc",
+            docId: "explanations/architecture_overview",
+            position: "left",
+            label: "Explanations",
+          },
+          {
+            type: "doc",
+            docId: "reference/overview",
+            position: "left",
+            label: "API Reference",
           },
           // { to: "/blog", label: "Blog", position: "left" },
           {
@@ -70,8 +82,16 @@ const config = {
             title: "Docs",
             items: [
               {
-                label: "Tutorial",
-                to: "/docs/quickstart",
+                label: "Guides",
+                to: "/docs/guides/quickstart",
+              },
+              {
+                label: "Explanations",
+                to: "/docs/explanations/architecture_overview",
+              },
+              {
+                label: "API Reference",
+                to: "/docs/reference/overview",
               },
             ],
           },

docs/web/sidebars.js

@@ -14,7 +14,33 @@
 /** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */
 const sidebars = {
   // By default, Docusaurus generates a sidebar from the docs folder structure
-  tutorialSidebar: [{ type: "autogenerated", dirName: "." }],
+  guides: [
+    { type: "autogenerated", dirName: "guides" },
+    {
+      type: "category",
+      label: "Tutorials",
+      collapsed: false,
+      items: [
+        {
+          type: "autogenerated",
+          dirName: "tutorials",
+        },
+      ],
+    },
+    {
+      type: "category",
+      label: "Contributors & Library Authors",
+      collapsed: true,
+      items: [
+        {
+          type: "autogenerated",
+          dirName: "contributors",
+        },
+      ],
+    },
+  ],
+  explanations: [{ type: "autogenerated", dirName: "explanations" }],
+  reference: [{ type: "autogenerated", dirName: "reference" }],
 
   // But you can create a sidebar manually
   /*

docs/web/src/pages/index.js

@@ -16,7 +16,7 @@ function HomepageHeader() {
         <div className={styles.buttons}>
           <Link
             className="button button--secondary button--lg"
-            to="/docs/quickstart"
+            to="/docs/guides/quickstart"
           >
             Mephisto Quickstart - 10min ⏱️
           </Link>