✨ Template: Add GitHub action for deploying docs on Github

Add a GitHub action to the template for both documentation tools to deploy the
documentation to GitHub pages. This will run for any pushes on the `main` branch.

The MkDocs action uses the `hatch docs:deploy` script, but the MyST deployment is more
convoluted. For now we simply add an action based generated by the
`myst init --gh-pages` command.

Author: mbercx

copier.yml

@@ -16,6 +16,14 @@ docs:
     - mkdocs
   default: myst
 
+doc_deploy:
+  type: str
+  help: 'Where do you want to deploy your documentation?'
+  choices:
+    - nowhere
+    - github
+  default: nowhere
+
 _subdirectory: template
 _message_after_copy: |
   The `{{package_name}}` package has been created successfully!

template/{% if doc_deploy == 'github' %}.github{% endif %}/workflows/{% if doc_deploy == 'github' and docs == 'myst' %}deploy-myst.yaml{% endif %}

@@ -0,0 +1,45 @@
+name: Deploy MyST site to Github pages
+on:
+  push:
+    # Runs on pushes targeting the default branch
+    branches: [main]
+env:
+  # `BASE_URL` determines, relative to the root of the domain, the URL that your site is served from.
+  # E.g., if your site lives at `https://mydomain.org/myproject`, set `BASE_URL=/myproject`.
+  # If, instead, your site lives at the root of the domain, at `https://mydomain.org`, set `BASE_URL=''`.
+  BASE_URL: /${{ github.event.repository.name }}
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: 'pages'
+  cancel-in-progress: false
+jobs:
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Setup Pages
+        uses: actions/configure-pages@v3
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 18.x
+      - name: Install MyST
+        run: npm install -g mystmd
+      - name: Build HTML Assets
+        run: myst build --html
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: './_build/html'
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

template/{% if doc_deploy == 'github' %}.github{% endif %}/workflows/{% if doc_deploy == 'github' and docs == 'mkdocs' %}deploy-mkdocs.yaml{% endif %}

@@ -0,0 +1,22 @@
+name: Deploy MkDocs site to Github pages
+on:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: 3.x
+
+      # Use configured `hatch` environment for MkDocs deployment
+      - run: pip install hatch
+      - run: hatch run docs:deploy