docs: enable mkdocs netlify build previews (#533)

Author: jgravois

.devcontainer/compose.yml

@@ -15,6 +15,6 @@ services:
     entrypoint: mkdocs
     command: serve --dev-addr "0.0.0.0:8001"
     ports:
-      - "8001:8001"
+      - 8001:8001
     volumes:
       - ../:/usr/src/calitp

.devcontainer/devcontainer.json

@@ -3,7 +3,6 @@
   "dockerComposeFile": "compose.yml",
   "service": "site",
   "runServices": ["site", "docs"],
-  "otherPortsAttributes": { "onAutoForward": "ignore" },
   "workspaceFolder": "/usr/src/calitp",
   "postAttachCommand": ["/bin/bash", ".devcontainer/postAttach.sh"],
   "customizations": {

.github/workflows/.python-version

@@ -0,0 +1 @@
+3.12

.github/workflows/mkdocs.yml

@@ -0,0 +1,75 @@
+name: Publish docs
+on:
+  pull_request:
+    branches:
+      - main
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+      - ".github/workflows/mkdocs.yml"
+
+env:
+  SANITIZED_REPO_NAME: "calitp-website"
+
+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@v6
+        with:
+          ref: "refs/pull/${{ github.event.number }}/merge"
+
+      - name: Setup Python
+        uses: actions/setup-python@v6
+        with:
+          python-version-file: .github/workflows/.python-version
+          cache: pip
+          cache-dependency-path: "docs/requirements.txt"
+
+      - name: Build MkDocs website
+        run: |
+          pip install -r docs/requirements.txt
+          mkdocs build
+
+      # it would speeds this action up significantly to cache this
+      - name: Install Netlify CLI
+        run: npm install --location=global netlify-cli@23
+
+      - name: Deploy Preview to Netlify
+        run: |
+          netlify deploy \
+            --alias="${SANITIZED_REPO_NAME}-${{ github.event.number }}" \
+            --auth=${{ secrets.NETLIFY_AUTH_TOKEN }} \
+            --dir="site" \
+            --site=${{ secrets.NETLIFY_PREVIEW_APP_SITE_ID }} \
+            --no-build \
+
+      - name: Find existing comment
+        uses: peter-evans/find-comment@v4
+        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@v8
+        if: steps.find-comment.outputs.comment-id == ''
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          script: |
+            const hostnamePrefix = process.env.SANITIZED_REPO_NAME
+            const hostnameSuffix = "cal-itp-previews.netlify.app"
+
+            github.rest.issues.createComment({
+              issue_number: context.issue.number,
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              body: `Preview url: https://${hostnamePrefix}-${{ github.event.number }}--${hostnameSuffix}`,
+            })

.gitignore

@@ -3,3 +3,4 @@
 .netlify
 _site
 .DS_Store
+site

README.md

@@ -46,7 +46,7 @@ We have a semi-automated way of handling resource requests that come in via GitH
 gh issue view <issue num> --json body | python .github/scripts/resource-template.py
 ```
 
-We have a GitHub Actions workflow that runs this script against all new issues and will automatically open a PR to add the requested resource, if the issue in fact appears to be a resource request and it is said to be approved. If an issue is opened initially for a resource that is not yet approved, the PR can be created automatically once the resource has been approved by going to [the workflow's page](https://github.com/cal-itp/calitp.org/actions/workflows/resource-template.yml) and using the **Run workflow** button.
+We have a GitHub Actions workflow that runs this script against all new issues and will automatically open a PR to add the requested resource, if the issue in fact appears to be a resource request and it is said to be approved. If an issue is opened initially for a resource that is not yet approved, the PR can be created automatically once the resource has been approved by going to [the workflow's page](./actions/workflows/resource-template.yml) and using the **Run workflow** button.
 
 ### Press
 

mkdocs.yml

@@ -1,7 +1,7 @@
-site_name: "cal-itp/calitp-dot-org: documentation"
+site_name: "cal-itp/calitp.org: documentation"
 repo_url: https://github.com/cal-itp/calitp.org
 edit_uri: edit/dev/docs
-site_url: https://docs.calitp.org/calitp-dot-org
+site_url: https://docs.calitp.org/calitp.org
 exclude_docs: |
   **/inc/*.md
 
@@ -26,7 +26,6 @@ plugins:
 
 extra_css:
   - styles/theme.css
-  - https://use.fontawesome.com/releases/v5.13.0/css/all.css
 
 markdown_extensions:
   - admonition