Feat: docs

.devcontainer/Dockerfile

@@ -20,6 +20,9 @@ COPY compiler_admin compiler_admin
 COPY pyproject.toml pyproject.toml
 RUN pip install -e .[dev,test]
 
+COPY docs/requirements.txt docs/requirements.txt
+RUN pip install -r docs/requirements.txt
+
 USER root
 RUN chown -R $USER:$USER /home/$USER
 USER $USER

.devcontainer/devcontainer.json

@@ -2,6 +2,8 @@
   "name": "compilerla/admin",
   "dockerComposeFile": ["../compose.yaml"],
   "service": "dev",
+  "runServices": ["dev", "docs"],
+  "forwardPorts": ["docs:8000"],
   "workspaceFolder": "/home/compiler/compiler-admin",
   "postAttachCommand": ["/bin/bash", ".devcontainer/postAttach.sh"],
   "customizations": {

.github/workflows/mkdocs.yml

@@ -0,0 +1,106 @@
+name: Publish docs
+on:
+  workflow_dispatch:
+  pull_request:
+    branches:
+      - main
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+      - ".github/workflows/mkdocs.yml"
+  push:
+    branches:
+      - main
+    paths:
+      - ".github/workflows/mkdocs.yml"
+      - "docs/**"
+      - ".markdownlint.yaml"
+      - "mkdocs.yml"
+
+jobs:
+  docs-preview:
+    name: Publish docs preview
+    runs-on: ubuntu-latest
+    # only pull requests should generate a preview
+    if: github.event.pull_request
+    permissions:
+      pull-requests: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          ref: "refs/pull/${{ github.event.number }}/merge"
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version-file: .github/workflows/.python-version
+          cache: pip
+          cache-dependency-path: |
+            "**/pyproject.toml"
+            "docs/requirements.txt"
+
+      - name: Build MkDocs website
+        run: |
+          pip install .[dev] -r docs/requirements.txt
+          mkdocs build
+
+      - name: Install Netlify CLI
+        run: npm install --location=global netlify-cli@17.x.x
+
+      - name: Deploy Preview to Netlify
+        run: |
+          netlify deploy \
+            --alias="${GITHUB_REPOSITORY#*/}-${{ github.event.number }}" \
+            --auth=${{ secrets.NETLIFY_AUTH_TOKEN }} \
+            --dir="site" \
+            --site=${{ vars.NETLIFY_PREVIEW_APP_SITE_ID }}
+
+      - name: Find existing comment
+        uses: peter-evans/find-comment@v3
+        id: find-comment
+        with:
+          issue-number: ${{ github.event.number }}
+          comment-author: "github-actions[bot]"
+          body-includes: "Preview url: https://"
+
+      - name: Add Netlify link PR comment
+        uses: actions/github-script@v7
+        if: steps.find-comment.outputs.comment-id == ''
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          script: |
+            const hostnameSuffix = "compiler-previews.netlify.app"
+            github.rest.issues.createComment({
+              issue_number: context.issue.number,
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              body: `Preview url: https://${context.repo.repo}-${{ github.event.number }}--${hostnameSuffix}`,
+            })
+
+  docs:
+    name: Publish docs
+    runs-on: ubuntu-latest
+    # don't publish for pull requests
+    if: github.event.pull_request == null
+    permissions:
+      contents: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version-file: .github/workflows/.python-version
+          cache: pip
+          cache-dependency-path: |
+            "**/pyproject.toml"
+            "docs/requirements.txt"
+
+      - name: Install MkDocs requirements
+        run: |
+          pip install .[dev] -r docs/requirements.txt
+
+      - name: Deploy MkDocs website
+        run: |
+          mkdocs gh-deploy --force

.markdownlint.yaml

@@ -0,0 +1,19 @@
+# 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
+
+# Allow inline HTML
+MD033: false
+
+# Allow duplicate headers
+MD024: false
+
+# Allow mixing code block and fenced code regions
+# Useful for pages with admonitions and fenced code blocks
+MD046: false

README.md

@@ -2,11 +2,15 @@
 
 Automating Compiler's administrative tasks.
 
-Built on top of [GAMADV-XTD3](https://github.com/taers232c/GAMADV-XTD3) and [GYB](https://github.com/GAM-team/got-your-back).
+Built on top of [GAM7](https://github.com/GAM-team/GAM) and [GYB](https://github.com/GAM-team/got-your-back).
 
 **Note:** This tool can only be used by those with administrator access to Compiler's Google Workspace.
 
-## Usage
+## Documentation
+
+For full installation, usage, and command reference, please see the [docs site](https://docs.compiler.la/compiler-admin).
+
+## Basic Usage
 
 ```bash
 $ compiler-admin -h
@@ -24,229 +28,3 @@ options:
   -h, --help            show this help message and exit
   -v, --version         show program's version number and exit
 ```
-
-## Getting started
-
-```bash
-mkdir -p ~/.config/compiler-admin
-
-git clone https://github.com/compilerla/compiler-admin.git
-
-cd compiler-admin
-```
-
-Now open in VS Code, and when prompted, reopen in the devcontainer.
-
-## Initial setup
-
-Initial setup of a GAMADV-XTD3 project and GYB project is required to provide necessary API access to the Google Workspace.
-
-```bash
-$ compiler-admin init -h
-usage: compiler-admin init [-h] [--gam] [--gyb] username
-
-positional arguments:
-  username    A Compiler user account name, sans domain.
-
-options:
-  -h, --help  show this help message and exit
-  --gam       If provided, initialize a new GAM project.
-  --gyb       If provided, initialize a new GYB project.
-```
-
-The `init` commands follows the steps in the [GAMADV-XTD3 Wiki](https://github.com/taers232c/GAMADV-XTD3/wiki/#requirements).
-
-Additionally, GYB is used for Gmail backup/restore. See the [GYB Wiki](https://github.com/GAM-team/got-your-back/wiki) for more information.
-
-## Working with time entires
-
-The `time` command provides an interface for working with time entries from Compiler's various systems:
-
-```bash
-$ compiler-admin time --help
-Usage: compiler-admin time [OPTIONS] COMMAND [ARGS]...
-
-  Work with Compiler time entries.
-
-Options:
-  --help  Show this message and exit.
-
-Commands:
-  convert   Convert a time report from one format into another.
-  download  Download a Toggl time report in CSV format.
-  lock      Lock Toggl time entries.
-  verify    Verify time entry CSV files.
-```
-
-### Locking time entries
-
-Use this command to lock Toggl time entries up to some date (defaulting to the last day of the prior month).
-
-```bash
-$ compiler-admin time lock --help
-Usage: compiler-admin time lock [OPTIONS]
-
-  Lock Toggl time entries.
-
-Options:
-  --date TEXT  The date to lock time entries, formatted as YYYY-MM-DD.
-               Defaults to the last day of the previous month.
-  --help       Show this message and exit.
-```
-
-### Downloading a Toggl report
-
-Use this command to download a time report from Toggl in CSV format (defaulting to the prior month):
-
-```bash
-$ compiler-admin time download --help
-Usage: compiler-admin time download [OPTIONS]
-
-  Download a Toggl time report in CSV format.
-
-Options:
-  --start YYYY-MM-DD        The start date of the reporting period. Defaults
-                            to the beginning of the prior month.
-  --end YYYY-MM-DD          The end date of the reporting period. Defaults to
-                            the end of the prior month.
-  --output TEXT             The path to the file where downloaded data should
-                            be written. Defaults to a path calculated from the
-                            date range.
-  --all                     Download all time entries. The default is to
-                            download only billable time entries.
-  -c, --client CLIENT_ID    An ID for a Toggl Client to filter for in reports.
-                            Can be supplied more than once.
-  -p, --project PROJECT_ID  An ID for a Toggl Project to filter for in
-                            reports. Can be supplied more than once.
-  -t, --task TASK_ID        An ID for a Toggl Project Task to filter for in
-                            reports. Can be supplied more than once.
-  -u, --user USER_ID        An ID for a Toggl User to filter for in reports.
-                            Can be supplied more than once.
-  --help                    Show this message and exit.
-```
-
-### Converting an hours report
-
-With a CSV exported from either Harvest or Toggl, use this command to convert to the opposite format:
-
-```bash
-$ compiler-admin time convert --help
-Usage: compiler-admin time convert [OPTIONS]
-
-  Convert a time report from one format into another.
-
-Options:
-  --input TEXT                    The path to the source data for conversion.
-                                  Defaults to $TOGGL_DATA or stdin.
-  --output TEXT                   The path to the file where converted data
-                                  should be written. Defaults to $HARVEST_DATA
-                                  or stdout.
-  --from [harvest|toggl]          The format of the source data.  [default:
-                                  toggl]
-  --to [harvest|justworks|toggl]  The format of the converted data.  [default:
-                                  harvest]
-  --client TEXT                   The name of the client to use in converted
-                                  data.
-  --help                          Show this message and exit.
-```
-
-### Verifying an hours conversion
-
-```bash
-$ compiler-admin time verify --help
-Usage: compiler-admin time verify [OPTIONS] [FILES]...
-
-  Verify time entry CSV files.
-
-Options:
-  --help  Show this message and exit.
-```
-
-## Working with users
-
-The following commands are available to work with users in the Compiler domain:
-
-```bash
-$ compiler-admin user -h
-usage: compiler-admin user [-h] {alumni,create,convert,delete,offboard,reset,restore,signout} ...
-
-positional arguments:
-  {alumni,create,convert,delete,offboard,reset,restore,signout}
-                        The user command to run.
-    alumni              Convert a user account to a Compiler alumni.
-    create              Create a new user in the Compiler domain.
-    convert             Convert a user account to a new type.
-    delete              Delete a user account.
-    offboard            Offboard a user account.
-    reset               Reset a user's password to a randomly generated string.
-    restore             Restore an email backup from a prior offboarding.
-    signout             Signs a user out from all active sessions.
-
-options:
-  -h, --help            show this help message and exit
-```
-
-### Creating a user
-
-```bash
-$ compiler-admin user create -h
-usage: compiler-admin user create [-h] [--notify NOTIFY] username
-
-positional arguments:
-  username         A Compiler user account name, sans domain.
-
-options:
-  -h, --help       show this help message and exit
-  --notify NOTIFY  An email address to send the newly created account info.
-```
-
-Additional options are passed through to GAM, see more about [GAM user create](https://github.com/taers232c/GAMADV-XTD3/wiki/Users#create-a-user)
-
-### Convert a user
-
-```bash
-$ compiler-admin user convert -h
-usage: compiler-admin user convert [-h] [--force] [--notify NOTIFY] username {alumni,contractor,partner,staff}
-
-positional arguments:
-  username              A Compiler user account name, sans domain.
-  {alumni,contractor,partner,staff}
-                        Target account type for this conversion.
-
-options:
-  -h, --help            show this help message and exit
-  --force               Don't ask for confirmation before conversion.
-  --notify NOTIFY       An email address to send the alumni's new password.
-```
-
-### Offboarding a user
-
-```bash
-$ compiler-admin user offboard -h
-usage: compiler-admin user offboard [-h] [--alias ALIAS] [--force] username
-
-positional arguments:
-  username       A Compiler user account name, sans domain.
-
-options:
-  -h, --help     show this help message and exit
-  --alias ALIAS  Account to assign username as an alias.
-  --force        Don't ask for confirmation before offboarding.
-```
-
-This script creates a local backup of `USER`'s inbox, see [Restore](#restore-an-email-backup)
-
-### Restore an email backup
-
-Retore a backup from a prior [Offboarding](#offboarding-a-user) into the `archive@compiler.la` account.
-
-```bash
-$ compiler-admin user restore -h
-usage: compiler-admin user restore [-h] username
-
-positional arguments:
-  username    The user's account name, sans domain.
-
-options:
-  -h, --help  show this help message and exit
-```