Replace template-devcontainer docs with the basics

.devcontainer/devcontainer.json

@@ -6,6 +6,9 @@
     "dev",
     "docs"
   ],
+  "forwardPorts": [
+    "docs:8001"
+  ],
   "workspaceFolder": "/compiler/app",
   "postCreateCommand": [
     "/bin/bash",

.github/workflows/mkdocs.yml

@@ -7,7 +7,6 @@ on:
     paths:
       - ".github/workflows/mkdocs.yml"
       - "docs/**"
-      - ".markdownlint.yaml"
       - "mkdocs.yml"
 
 jobs:

.markdownlint.yaml

@@ -1,10 +1,6 @@
 # includes/excludes all rules by default
 default: true
 
-# 4-space list indentation works best with MkDocs
-MD007:
-  indent: 4
-
 # Remove line length limit - no one wants to hard wrap all their paragraphs
 MD013: false
 

docs/.pages

@@ -1,4 +1,4 @@
 nav:
   - Home: README.md
-  - Features: features
-  - Usage: usage
+  - Setup: setup.md
+  - Development: development.md

docs/README.md

@@ -1,45 +1,21 @@
-# template-devcontainer Docs
+# Slackronyms Docs
 
 ## Introduction
 
-This is the documentation site for [`compilerla/template-devcontainer`](https://github.com/compilerla/template-devcontainer).
+This is the documentation site for [`compilerla/slackronyms`](https://github.com/compilerla/slackronyms), an open-source Slack app to help teams keep track of acronyms and other abbreviations.
 
-`template-devcontainer` is a [template repository](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-template-repository)
-with a minimal [VS Code devcontainer](https://code.visualstudio.com/docs/remote/containers) setup.
+## Usage
 
-`template-devcontainer` can be used as the basis for another language-specific devcontainer,
-or as a quick ready-made Linux development environment.
+When added to your workspace, Slackronyms provides a `/define` command that is used to both ouput and set definitions for a term, depending on the way the command is formatted.
 
-Docs are built using [`mkdocs`](https://www.mkdocs.org/). This site is built using [`mkdocs-material`](https://squidfunk.github.io/mkdocs-material/).
+### `/define <term>`
 
-## Use this template
+Outputs a definition for the given term as a public message in the current channel. The output does not reveal the identity of the person who requested it.
 
-[Generate a new repository from the template](https://github.com/compilerla/template-devcontainer/generate){.md-button}
+![example output from running the command /define TDQ](img/define-output-example.png)
 
-## Why?
+### `/define <term>: <definition>`
 
-In no particular order, here are some reasons Compiler likes to use devcontainers as part of our software engineering workflow:
+Appending a colon and a definition to a basic `/define <term>` command will set the definition for that term.
 
-_Read more in our blog post: [How to support a platform-agnostic engineering team with VS Code Dev Containers](https://compiler.la/blog/2024/devcontainer-platform-agnostic-team)_.
-
-| Reason                     | More                                                                                                                                                                                                                                                                                                                           |
-| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| **Cross-platform**         | With only VS Code and Docker as dependencies, devcontainers allow developers on Linux, Mac, and Windows to work in a consistent environment, no matter the project's stack                                                                                                                                                     |
-| **Easily extendable**      | The VS Code community maintains a [library of extensions](https://marketplace.visualstudio.com/VSCode) to add features and functionality to the development environment; individual personalizations can be made via [dotfiles](https://code.visualstudio.com/docs/remote/containers#_personalizing-with-dotfile-repositories) |
-| **Enforce best practices** | Baking linters, `pre-commit` checks, test runners, and more into the devcontainer ensures the team's best practices are no-brainer always-on features of the development workflow                                                                                                                                              |
-| **Rapid onboarding**       | By minimizing the steps from `git clone` to getting tests to pass or the app running locally, devcontainers make it easier to onboard as a new developer and spend time contributing instead of wallowing in environment setup                                                                                                 |
-| **Unified code style**     | With common editor settings like code formatting on save, standard indentation characters and spacing, consistent line endings, and more, the team never has to worry about what the code looks like or accidentally committing BOMs                                                                                           |
-
-## Prior art
-
-This template was informed by our work on recent projects as a remote-first, cross-platform development team.
-
-Some of our recent work built on the devcontainer pattern includes:
-
-- [`cal-itp/benefits`](https://github.com/cal-itp/benefits) (Python/Django web app)
-- [`cal-itp/eligibility-api`](https://github.com/cal-itp/eligibility-api) (Python API library)
-- [`cal-itp/eligibility-server`](https://github.com/cal-itp/eligibility-server) (Python/Flask API server)
-- [`cal-itp/hashfields`](https://github.com/cal-itp/hashfields) (Python CLI tool)
-- [`cal-itp/mobility-marketplace`](https://github.com/cal-itp/mobility-marketplace) (Jekyll static site)
-- [`compilerla/compiler.la`](https://github.com/compilerla/compiler.la) (Jekyll static site)
-- [`compilerla/conventional-pre-commit`](https://github.com/compilerla/conventional-pre-commit) (Python pre-commit hook)
+![example output from running the command /define CDT: California Department of Technology](img/define-set-example.png)

docs/development.md

@@ -0,0 +1,50 @@
+# Development
+
+!!! info "See also"
+
+    VS Code tutorial: [Remote development in Containers](https://code.visualstudio.com/docs/devcontainers/tutorial)
+
+## Setting up the dev container
+
+We include a [Dev Container](https://code.visualstudio.com/docs/devcontainers/containers) configuration to help with local testing and development.
+
+First, follow the [Setup](../setup/) steps to create the app in your Slack workspace and load your keys into a `.env` file.
+
+**The first time you run this project** you'll have to manually build the app container in your terminal, because the dev container is built from the app container.
+
+```sh
+docker compose build app
+```
+
+From there, connect to the dev container to begin working on the project:
+
+1. Open the repository directory in VS Code
+1. <kbd>Ctrl</kbd>/<kbd>Cmd</kbd>+<kbd>Shift</kbd>+<kbd>P</kbd> to bring up the Command Palette
+1. Start typing `devcontainers` to filter the command list
+1. Select **Rebuild and Reopen in Container** to start from scratch
+1. Select **Reopen in Container** to reopen the last dev container used
+
+Once inside the dev container, you have to manually start the app by pressing <kbd>F5</kbd> (or switch the primary sidebar to Run and Debug and click the play button).
+
+You should see output in a new terminal indicating that the app is now running, and you should now be able to invoke it in your Slack test workspace! Try the `/define` command to confirm.
+
+!!! important
+    After modifying app code, it will need to be restarted for the changes to take effect. Press <kbd>Ctrl</kbd>/<kbd>Cmd</kbd>+<kbd>Shift</kbd>+<kbd>F5</kbd> to restart it (or click the refresh icon that appeared in the top menu bar). Your updated code will now be invoked the next time you run a command in Slack.
+
+The app can be stopped with <kbd>Shift</kbd>+<kbd>F5</kbd> (or the stop icon in the top menu bar).
+
+To exit the dev container, use the **Reopen Folder Locally** command.
+
+## Run the tests
+
+Python unit tests are written with [`pytest`](https://docs.pytest.org/en/latest/) and can be run when the dev container is open by using the VS Code Testing sidebar or in a terminal:
+
+1. Open a new terminal
+
+1. ```bash
+   cd slackronyms/
+   ```
+
+1. ```bash
+   pytest
+   ```

docs/setup.md

@@ -0,0 +1,48 @@
+# Setup
+
+Setting up this Slack app requires two main things:
+
+1. A Slack workspace where you have permission to install apps (or can request it)
+1. Standing up the application provided in the `slackronyms` folder of this repo somewhere it can run persistently
+
+## 1. Create and install your Slack app
+
+1. Open [https://api.slack.com/apps/new](https://api.slack.com/apps/new) and choose **From a manifest**.
+1. Choose the workspace you want to install the application to.
+1. Replace the contents of the JSON code block with the contents of [`manifest.json`](https://github.com/compilerla/slackronyms/blob/main/slackronyms/manifest.json).
+1. Review the configuration and click **Create**.
+1. Click **Install to Workspace** and **Allow** on the screen that follows. You'll then be redirected to the App Configuration dashboard.
+
+The app is now "installed" in the workspace, but it won't do anything until it can connect to the running code.
+
+## 2. Stand up the Python app
+
+### Prerequisites
+
+- An environment where you can run a Python 3.14 app
+- A place to store the JSON file that holds the terms and definitions data
+  - This could be the local filesystem of the Python app, if it's persistent (e.g., an EC2 instance).
+  - If you use the container provided in `appcontainer/Dockerfile`, you'll need to store the file in some other location and configure the app to read and write from that.
+
+### Environment Variables
+
+Before you can run the app, you'll need to store some environment variables. If you're planning to use the containerized app, you can do this by creating a `.env` file and using the `docker compose` configuration provided in `compose.yml` to start the container.
+
+1. Create a `.env` file from the sample at the root of the repo:
+
+   ```sh
+   cp .env.sample .env
+   ```
+
+1. Open your app's configuration page from [this list](https://api.slack.com/apps), click **OAuth & Permissions** in the left hand menu, then copy the Bot User OAuth Token. Paste it for `SLACK_BOT_TOKEN` in your `.env` file.
+1. Click **Basic Information** from the left hand menu and follow the steps in the App-Level Tokens section to create an app-level token with the `connections:write` scope. Copy this token and paste it for `SLACK_APP_TOKEN` in your `.env` file.
+
+### Running the application
+
+A `Dockerfile` is provided in the `appcontainer` folder that will install necessary dependencies and run the app. To build and run it:
+
+```sh
+docker compose up app
+```
+
+You should see output in a new terminal indicating that the app is now running, and you should now be able to invoke it in your Slack test workspace! Try the `/define` command to confirm.