✨ Add support for previewing docs in PRs from forks and enable MkDocs…

… Insiders (#357)

.github/actions/comment-docs-preview-in-pr/Dockerfile

@@ -0,0 +1,7 @@
+FROM python:3.7
+
+RUN pip install httpx "pydantic==1.5.1" pygithub
+
+COPY ./app /app
+
+CMD ["python", "/app/main.py"]

.github/actions/comment-docs-preview-in-pr/action.yml

@@ -0,0 +1,13 @@
+name: Comment Docs Preview in PR
+description: Comment with the docs URL preview in the PR
+author: Sebastián Ramírez <tiangolo@gmail.com>
+inputs:
+  token:
+    description: Token for the repo. Can be passed in using {{ secrets.GITHUB_TOKEN }}
+    required: true
+  deploy_url:
+    description: The deployment URL to comment in the PR
+    required: true
+runs:
+  using: docker
+  image: Dockerfile

.github/actions/comment-docs-preview-in-pr/app/main.py

@@ -0,0 +1,70 @@
+import logging
+import sys
+from pathlib import Path
+from typing import Optional
+
+import httpx
+from github import Github
+from github.PullRequest import PullRequest
+from pydantic import BaseModel, BaseSettings, SecretStr, ValidationError
+
+github_api = "https://api.github.com"
+
+
+class Settings(BaseSettings):
+    github_repository: str
+    github_event_path: Path
+    github_event_name: Optional[str] = None
+    input_token: SecretStr
+    input_deploy_url: str
+
+
+class PartialGithubEventHeadCommit(BaseModel):
+    id: str
+
+
+class PartialGithubEventWorkflowRun(BaseModel):
+    head_commit: PartialGithubEventHeadCommit
+
+
+class PartialGithubEvent(BaseModel):
+    workflow_run: PartialGithubEventWorkflowRun
+
+
+if __name__ == "__main__":
+    logging.basicConfig(level=logging.INFO)
+    settings = Settings()
+    logging.info(f"Using config: {settings.json()}")
+    g = Github(settings.input_token.get_secret_value())
+    repo = g.get_repo(settings.github_repository)
+    try:
+        event = PartialGithubEvent.parse_file(settings.github_event_path)
+    except ValidationError as e:
+        logging.error(f"Error parsing event file: {e.errors()}")
+        sys.exit(0)
+    use_pr: Optional[PullRequest] = None
+    for pr in repo.get_pulls():
+        if pr.head.sha == event.workflow_run.head_commit.id:
+            use_pr = pr
+            break
+    if not use_pr:
+        logging.error(
+            f"No PR found for hash: {event.workflow_run.head_commit.id}"
+        )
+        sys.exit(0)
+    github_headers = {
+        "Authorization": f"token {settings.input_token.get_secret_value()}"
+    }
+    url = f"{github_api}/repos/{settings.github_repository}/issues/{use_pr.number}/comments"
+    logging.info(f"Using comments URL: {url}")
+    response = httpx.post(
+        url,
+        headers=github_headers,
+        json={
+            "body": f"📝 Docs preview for commit {use_pr.head.sha} at: {settings.input_deploy_url}"
+        },
+    )
+    if not (200 <= response.status_code <= 300):
+        logging.error(f"Error posting comment: {response.text}")
+        sys.exit(1)
+    logging.info("Finished")

.github/workflows/build-docs.yml

@@ -0,0 +1,72 @@
+name: Build Docs
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+    types: [opened, synchronize]
+  workflow_dispatch:
+    inputs:
+      debug_enabled:
+        description: 'Run the build with tmate debugging enabled (https://github.com/marketplace/actions/debugging-with-tmate)'     
+        required: false
+        default: false
+jobs:
+  build-docs:
+    runs-on: ubuntu-20.04
+    steps:
+      - name: Dump GitHub context
+        env:
+          GITHUB_CONTEXT: ${{ toJson(github) }}
+        run: echo "$GITHUB_CONTEXT"
+      - uses: actions/checkout@v2
+      - name: Set up Python
+        uses: actions/setup-python@v2
+        with:
+          python-version: "3.7"
+      # Allow debugging with tmate
+      - name: Setup tmate session
+        uses: mxschmitt/action-tmate@v3
+        if: ${{ github.event_name == 'workflow_dispatch' && github.event.inputs.debug_enabled }}
+        with:
+          limit-access-to-actor: true
+      - uses: actions/cache@v2
+        id: cache
+        with:
+          path: ${{ env.pythonLocation }}
+          key: ${{ runner.os }}-python-${{ env.pythonLocation }}-${{ hashFiles('pyproject.toml') }}-docs
+      - name: Install Flit
+        if: steps.cache.outputs.cache-hit != 'true'
+        run: python3.7 -m pip install flit
+      - name: Install docs extras
+        if: steps.cache.outputs.cache-hit != 'true'
+        run: python3.7 -m flit install --extras doc
+      - name: Install Material for MkDocs Insiders
+        if: github.event.pull_request.head.repo.fork == false && steps.cache.outputs.cache-hit != 'true'
+        run: python3.7 -m pip install git+https://${{ secrets.ACTIONS_TOKEN }}@github.com/squidfunk/mkdocs-material-insiders.git
+      - uses: actions/cache@v2
+        with:
+          key: mkdocs-cards-${{ github.ref }}
+          path: .cache
+      - name: Build Docs
+        if: github.event.pull_request.head.repo.fork == true
+        run: python3.7 -m mkdocs build
+      - name: Build Docs with Insiders
+        if: github.event.pull_request.head.repo.fork == false
+        run: python3.7 -m mkdocs build --config-file mkdocs.insiders.yml
+      - name: Zip docs
+        run: bash ./scripts/zip-docs.sh
+      - uses: actions/upload-artifact@v2
+        with:
+          name: docs-zip
+          path: ./docs.zip
+      - name: Deploy to Netlify
+        uses: nwtgck/actions-netlify@v1.1.5
+        with:
+          publish-dir: './site'
+          production-branch: master
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          enable-commit-comment: false
+        env:
+          NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}
+          NETLIFY_SITE_ID: ${{ secrets.NETLIFY_SITE_ID }}

.github/workflows/preview-docs.yml

@@ -0,0 +1,41 @@
+name: Preview Docs
+on:
+  workflow_run:
+    workflows:
+      - Build Docs
+    types: 
+      - completed
+
+jobs:
+  preview-docs:
+    runs-on: ubuntu-20.04
+    steps:
+      - uses: actions/checkout@v2
+      - name: Download Artifact Docs
+        uses: dawidd6/action-download-artifact@v2.9.0
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          workflow: build-docs.yml
+          run_id: ${{ github.event.workflow_run.id }}
+          name: docs-zip
+      - name: Unzip docs
+        run: |
+          rm -rf ./site
+          unzip docs.zip
+          rm -f docs.zip
+      - name: Deploy to Netlify
+        id: netlify
+        uses: nwtgck/actions-netlify@v1.1.5
+        with:
+          publish-dir: './site'
+          production-deploy: false
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          enable-commit-comment: false
+        env:
+          NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}
+          NETLIFY_SITE_ID: ${{ secrets.NETLIFY_SITE_ID }}
+      - name: Comment Deploy
+        uses: ./.github/actions/comment-docs-preview-in-pr
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          deploy_url: "${{ steps.netlify.outputs.deploy-url }}"

mkdocs.insiders.yml

@@ -0,0 +1,4 @@
+INHERIT: mkdocs.yml
+plugins:
+  - search
+  - social

scripts/zip-docs.sh

@@ -0,0 +1,9 @@
+#! /usr/bin/env bash
+
+set -x
+set -e
+
+if [ -f docs.zip ]; then
+    rm -rf docs.zip
+fi
+zip -r docs.zip ./site