cli: Move the documentation to markdown

algobowl/templates/cli_setup.xhtml

@@ -14,66 +14,13 @@
         in the CLI.
       </p>
 
-      <h2>Installation</h2>
+      <a href="https://github.com/jackrosenthal/algobowl/blob/main/docs/cli.md"
+         target="_blank"
+         class="btn btn-large btn-primary">
+       <i class="fas fa-book fa-fw"></i> Documentation
+      </a>
 
-      <p>
-      Download the
-      <a href="https://raw.githubusercontent.com/jackrosenthal/algobowl/main/cli_launcher.py">launcher script</a>
-      and mark it executable.  For example:
-      </p>
-
-      <p>
-        <tt>curl https://raw.githubusercontent.com/jackrosenthal/algobowl/main/cli_launcher.py -o algobowl &amp;&amp; chmod +x algobowl</tt>
-      </p>
-
-      <p>
-        You can either put it in a location referenced by your <tt>PATH</tt>
-        environment variable and run it as <tt>algobowl</tt>, or it's designed
-        so you can check it in to your group's Git repo as well (and run it as
-        <tt>./algobowl</tt>).
-      </p>
-
-      <p>
-        The launcher is designed to depend on nothing but Python 3.8+, so you
-        don't need to worry about installing any dependencies.
-      </p>
-
-      <h3>Authentication</h3>
-
-      <p>
-        Run <tt>algobowl auth login</tt> and follow the instructions.
-      </p>
-
-      <h2>Usage</h2>
-
-      <p>
-        Run <tt>algobowl --help</tt> for help.  Here are some commands you may
-        be interested in:
-      </p>
-
-      <h3>Input Upload</h3>
-
-      <ul>
-        <li><tt>algobowl group input upload FILENAME</tt>: Upload your group's input.</li>
-        <li><tt>algobowl group input download OUTPUT_FILE</tt>: Download your group's input.</li>
-        <li><tt>algobowl group set-team-name TEAM_NAME</tt>: Set your team name.</li>
-      </ul>
-
-      <h3>Output Upload</h3>
-
-      <ul>
-        <li><tt>algobowl group output --to-group-id GROUP_ID upload FILENAME</tt>: Upload an output.</li>
-        <li><tt>algobowl group output --to-group-id GROUP_ID download OUTPUT_FILE</tt>: Download one of your submitted outputs.</li>
-        <li><tt>algobowl group output list</tt>: List output files you'll need to provide.</li>
-      </ul>
-
-      <p>
-        Note: if you use filenames containing the group ID, (e.g.,
-        <tt>output_group123.txt</tt>), the CLI can infer the group ID from the
-        filename, and passing <tt>--to-group-id</tt> is not required.
-      </p>
-
-      <h2>Logged-in Clients</h2>
+      <h2 class="mt-3">Logged-in Clients</h2>
 
       <p>
         Your currently logged-in clients are listed below.

docs/cli.md

@@ -0,0 +1,74 @@
+# AlgoBOWL CLI
+
+The AlgoBOWL CLI provides convenient access to interact with AlgoBOWL from your
+command line and from scripts.
+
+**The CLI is still very much in beta state, and not complete yet.**
+Improvements are welcome (send patches!)
+
+## System Requirements
+
+The only requirement is Python 3.8 or newer.  The CLI is best-supported on
+Linux, however, it may work on Windows and Mac as well.  Patches are welcome
+if it doesn't work on Windows or Mac.
+
+## Installation
+
+Download [`cli_launcher.py`](../cli_launcher.py) and mark it executable.  It's
+recommended to name this file `algobowl` and put it somewhere on your `PATH`.
+Alternatively, you could download it into your group's Git repository and use it
+as `./algobowl` from there.
+
+``` shellsession
+$ curl https://raw.githubusercontent.com/jackrosenthal/algobowl/main/cli_launcher.py -o algobowl && chmod +x algobowl
+```
+
+The CLI launcher will download the CLI and dependencies, and keep them up to
+date as required.  If you prefer to manage your own installation, or plan on
+hacking on the CLI source code, you can install an "editable copy" of this
+repository using `pip` instead:
+
+``` shellsession
+$ pip install -e .
+```
+
+## Usage
+
+Detailed usage can be found by running `algobowl --help`.
+
+### Authenticating to an AlgoBOWL server
+
+Run `algobowl auth login` and follow the instructions.  You can then verify
+you've successfully logged in by running `algobowl auth whoami`.
+
+The default server is `https://mines.algobowl.org`.  You can choose another
+server by running `algobowl config set-default-server ...`.
+
+### Group Commands
+
+You can perform actions on behalf of your group using `algobowl group` commands.
+By default, if you're only a member of one active group, it'll be selected for
+group commands.  If you're a member of multiple groups, or you're a site
+administrator and want to act on behalf of another group, you can pass
+`--group-id` to specify your group ID.  Here are some commands which may be of
+interest:
+
+#### Input Upload
+
+* `algobowl group input upload FILENAME`: Upload your group's input.
+* `algobowl group input download OUTPUT_FILE`: Download your group's input.
+* `algobowl group set-team-name TEAM_NAME`: Set your team name.
+
+#### Output Upload
+
+* `algobowl group output --to-group-id GROUP_ID upload FILENAME`: Upload an
+   output.
+* `algobowl group output --to-group-id GROUP_ID download OUTPUT_FILE`: Download
+   one of your submitted outputs.
+* `algobowl group output list`: List output files you'll need to provide.
+
+Note: if you use filenames containing the group ID, (e.g.,
+`output_group123.txt`), the CLI can infer the group ID from the filename, and
+passing `--to-group-id` is not required.  When multiple IDs appear in the
+filename (e.g., `output_from_group120_to_group123.txt`), the second ID
+is used.

docs/problem_format.md

@@ -32,7 +32,10 @@ required to implement on their own.
 Validate you have access (requesting it from Jack if necessary).  This is where
 you are going to push your problem implementation.
 
-## Setup AlgoBOWL development environment
+## Set up the AlgoBOWL CLI
+
+The AlgoBOWL CLI is used to run the problem tester.  Set it up by following
+[these instructions](./cli.md).
 
 Clone this repository, and create a new Python virtual environment: