Merge pull request #70 from cal-itp/mkdocs

initial mkdocs configuration, Docker Compose service for localhost, GitHub Action to build + deploy to GitHub Pages

Author: thekaveman

.devcontainer.json

@@ -3,7 +3,7 @@
     "name": "Benefits",
     "dockerComposeFile": ["./docker-compose.yml"],
     "service": "dev",
-    "runServices": ["dev", "server"],
+    "runServices": ["dev", "docs", "server"],
     "workspaceFolder": "/home/calitp/app",
     "postStartCommand": ["/bin/bash", "bin/init.sh"],
     "postAttachCommand": ["/bin/bash", "bin/pre-commit.sh"],

.env.sample

@@ -17,3 +17,6 @@ DJANGO_INIT_PATH=data/client.json
 DJANGO_LOCAL_PORT=8000
 DJANGO_LOG_LEVEL=DEBUG
 DJANGO_SECRET_KEY=secret
+
+# mkdocs config
+DOCS_LOCAL_PORT=8001

.github/workflows/mkdocs.yml

@@ -0,0 +1,20 @@
+name: Publish docs
+on:
+  push:
+    branches:
+      - dev
+
+jobs:
+  docs:
+    name: Publish docs
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v2
+
+      - name: Deploy docs
+        uses: mhausenblas/mkdocs-deploy-gh-pages@master
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          CUSTOM_DOMAIN: docs.calitp.org
+          CONFIG_FILE: docs/mkdocs.yml

.pre-commit-config.yaml

@@ -13,6 +13,7 @@ repos:
       - id: end-of-file-fixer
       - id: requirements-txt-fixer
       - id: check-yaml
+        args: ["--unsafe"]
       - id: check-added-large-files
 
   - repo: https://github.com/psf/black

Dockerfile.dev

@@ -3,4 +3,6 @@ FROM benefits_client:latest
 USER root
 
 RUN apt-get install -qq --no-install-recommends curl git jq ssh && \
-    pip install --no-cache-dir flake8 debugpy pre-commit
+    pip install --no-cache-dir flake8 debugpy pre-commit \
+        mkdocs mkdocs-material mkdocs-awesome-pages-plugin \
+        fontawesome_markdown mdx_truly_sane_lists mkdocs-macros-plugin

docker-compose.yml

@@ -43,6 +43,15 @@ services:
     volumes:
       - .:/home/calitp/app:cached
 
+  docs:
+    image: benefits_client:dev
+    entrypoint: []
+    command: mkdocs serve --config-file docs/mkdocs.yml --dev-addr "0.0.0.0:8001"
+    ports:
+      - "${DOCS_LOCAL_PORT}:8001"
+    volumes:
+      - .:/home/calitp/app:cached
+
   server:
     build: ./server
     image: eligibility_verification_server:dev

docs/README.md

@@ -0,0 +1,4 @@
+# Home
+
+This is the documentation website for [`benefits`](https://github.com/cal-itp/benefits)
+from Cal-ITP, the [California Integrated Travel Project](https://calitp.org).

docs/mkdocs.yml

@@ -0,0 +1,44 @@
+site_name: Benefits Documentation
+repo_url: https://github.com/cal-itp/benefits
+edit_uri: edit/dev/docs
+docs_dir: ./
+site_url: https://docs.calitp.org/benefits
+
+theme:
+  name: material
+  features:
+    - navigation.tabs
+  palette:
+    primary: "blue"
+    accent: "amber"
+
+plugins:
+  - search
+  - awesome-pages
+
+extra_javascript:
+  - https://unpkg.com/mermaid@8.5.0/dist/mermaid.min.js
+
+extra_css:
+  - https://use.fontawesome.com/releases/v5.13.0/css/all.css
+
+markdown_extensions:
+  - admonition
+  - codehilite:
+      linenums: true
+  - pymdownx.inlinehilite
+  - pymdownx.tasklist:
+      custom_checkbox: true
+  - pymdownx.tabbed
+  - pymdownx.superfences:
+      custom_fences:
+        - name: mermaid
+          class: mermaid
+          format: !!python/name:pymdownx.superfences.fence_div_format
+  - pymdownx.smartsymbols
+  - meta
+  - toc:
+      # insert a blank space before the character
+      permalink: " ¶"
+  - smarty
+  - fontawesome_markdown