Feat: set up docs

.devcontainer/Dockerfile

@@ -28,6 +28,9 @@ COPY . .
 # install devcontainer requirements
 RUN pip install --no-cache-dir -r .devcontainer/requirements.txt
 
+# install docs requirements
+RUN pip install --no-cache-dir -r docs/requirements.txt
+
 # install pre-commit environments in throwaway Git repository
 # https://stackoverflow.com/a/68758943
 RUN git init . && \

.devcontainer/devcontainer.json

@@ -2,7 +2,8 @@
   "name": "caltrans/pems",
   "dockerComposeFile": ["../compose.yml"],
   "service": "dev",
-  "runServices": ["dev"],
+  "runServices": ["dev", "docs"],
+  "forwardPorts": ["docs:8000"],
   "workspaceFolder": "/home/caltrans/src",
   "postAttachCommand": ["/bin/bash", ".devcontainer/postAttach.sh"],
   "customizations": {
@@ -18,6 +19,8 @@
       },
       // Add the IDs of extensions you want installed when the container is created.
       "extensions": [
+        "bpruitt-goddard.mermaid-markdown-syntax-highlighting",
+        "DavidAnson.vscode-markdownlint",
         "eamodio.gitlens",
         "esbenp.prettier-vscode",
         "mhutchie.git-graph"

.github/workflows/mkdocs.yml

@@ -0,0 +1,25 @@
+name: Publish docs
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - main
+    paths:
+      - ".github/workflows/mkdocs.yml"
+      - "docs/**"
+      - ".markdownlint.yaml"
+      - "mkdocs.yml"
+
+jobs:
+  docs:
+    name: Publish docs
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Deploy docs
+        uses: mhausenblas/mkdocs-deploy-gh-pages@master
+        env:
+          REQUIREMENTS: docs/requirements.txt
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.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

.pre-commit-config.yaml

@@ -13,6 +13,11 @@ repos:
       - id: conventional-pre-commit
         stages: [commit-msg]
 
+  - repo: https://github.com/igorshubovych/markdownlint-cli
+    rev: v0.42.0
+    hooks:
+      - id: markdownlint
+
   - repo: https://github.com/pre-commit/pre-commit-hooks
     rev: v5.0.0
     hooks:

.vscode/settings.json

@@ -1,9 +1,15 @@
 {
   "editor.formatOnSave": true,
   "editor.defaultFormatter": "esbenp.prettier-vscode",
+  "files.associations": {
+    ".pages": "yaml"
+  },
   "files.encoding": "utf8",
   "files.eol": "\n",
   "files.insertFinalNewline": true,
   "files.trimFinalNewlines": true,
-  "files.trimTrailingWhitespace": true
+  "files.trimTrailingWhitespace": true,
+  "[markdown]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
+  }
 }

compose.yml

@@ -8,3 +8,12 @@ services:
     image: caltrans/pems:main
     volumes:
       - ./:/home/caltrans/src
+
+  docs:
+    image: caltrans/pems:main
+    entrypoint: mkdocs
+    command: serve --dev-addr "0.0.0.0:8000"
+    ports:
+      - "8000"
+    volumes:
+      - ./:/home/caltrans/src

docs/.pages

@@ -0,0 +1,2 @@
+nav:
+  - Home: README.md

docs/README.md

@@ -0,0 +1,5 @@
+# PeMS
+
+Caltrans Performance Measurement System
+
+PeMS is open-source software that is designed, developed, and maintained by [Compiler LLC](https://compiler.la) on behalf of Caltrans Traffic Operations.

docs/requirements.txt

@@ -0,0 +1,6 @@
+mdx_truly_sane_lists
+mkdocs==1.6.1
+mkdocs-awesome-pages-plugin
+mkdocs-macros-plugin
+mkdocs-material==9.5.44
+mkdocs-redirects

mkdocs.yml

@@ -0,0 +1,65 @@
+site_name: "caltrans/pems: Documentation"
+repo_url: https://github.com/compilerla/pems
+edit_uri: edit/main/docs
+site_url: https://compilerla.github.io/pems
+
+theme:
+  name: material
+  features:
+    - navigation.expand
+    - navigation.tabs
+    - toc.integrate
+  palette:
+    - media: "(prefers-color-scheme: light)"
+      scheme: default
+      primary: blue
+      accent: green
+      toggle:
+        icon: material/toggle-switch-off-outline
+        name: Switch to dark mode
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      primary: blue
+      accent: green
+      toggle:
+        icon: material/toggle-switch
+        name: Switch to light mode
+
+extra:
+  analytics:
+    provider: google
+    property: G-xxxxxxxxxx
+
+plugins:
+  - search
+  - awesome-pages
+  - redirects:
+      redirect_maps:
+
+extra_css:
+  - https://use.fontawesome.com/releases/v6.1.2/css/all.css
+
+markdown_extensions:
+  - admonition
+  - attr_list
+  - codehilite:
+      linenums: true
+  - mdx_truly_sane_lists
+  - pymdownx.emoji:
+      emoji_index: !!python/name:materialx.emoji.twemoji
+      emoji_generator: !!python/name:materialx.emoji.to_svg
+  - pymdownx.inlinehilite
+  - pymdownx.tasklist:
+      custom_checkbox: true
+  - pymdownx.tabbed
+  - pymdownx.superfences:
+      custom_fences:
+        - name: mermaid
+          class: mermaid
+          format: !!python/name:pymdownx.superfences.fence_code_format
+  - pymdownx.smartsymbols
+  - meta
+  - toc:
+      # insert a blank space before the character
+      permalink: " ¶"
+  - smarty