📚 Docs (#23)

* Init mkdocs with gh action * Deploy 0.8 * Fix external link * Add git user qm-bot * Push changes * Fetch full commit history * Fixed input name * Apply mike versioning in mkdocs.yml * Add basic usage * Add override for outdated versions * Update aliases * Try without instant loading * Fix deploy cli args * Reload instant nav * Get latest version title from list of versions * Split git user to action step * Fix yml list
quaternionmedia · Apr 2, 2023 · a24fe28 · a24fe28
1 parent b106bd8
commit a24fe28
Show file tree

Hide file tree

Showing 5 changed files with 171 additions and 0 deletions.
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -0,0 +1,36 @@
+name: docs
+on:
+  push:
+    branches:
+      - main
+      - docs
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: 📰 Checkout
+        uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+
+      - name: 🐍 Setup Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: 3.x
+
+      - name: 🚧 Install dependencies
+        run: pip install mkdocs-material mkdocs-git-revision-date-localized-plugin mike
+
+      - name: 🤖 Configure git user
+        uses: oleksiyrudenko/gha-git-credentials@v2.1
+        with:
+          global: true
+          name: qm-bot
+          email: qm-bot@quaternion.media
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: 🧵 Set version string
+        run: echo VERSION_TITLE=$(mike list | grep latest) >> $GITHUB_ENV
+
+      - name: 🏗️ Deploy
+        run: mike deploy --push --update-aliases ${VERSION_TITLE%\[latest\]} latest
diff --git a/docs/index.md b/docs/index.md
@@ -0,0 +1,10 @@
+# Milestones
+
+Github action to create draft releases from closed milestones.
+
+## Marketplace
+Available on GitHub marketplace: [draft-release](https://github.com/marketplace/actions/draft-release)
+
+## Credits
+
+[Quaternion Media, LLC](https://quaternion.media)
diff --git a/docs/usage.md b/docs/usage.md
@@ -0,0 +1,33 @@
+# Usage
+
+## Setup
+To use this action, simple place the following file in your `.github/workflows/` folder.
+
+```yml title=".github/workflows/draft-release.yml"
+name: 📦 Release
+on:
+  milestone:
+    types: [closed]
+jobs:
+  release:
+    name: 📝 Draft Release
+    runs-on: ubuntu-latest
+    steps:
+      - name: 📰 Checkout
+        uses: actions/checkout@v3
+
+      - name: 📦 Create draft release from milestone
+        uses: quaternionmedia/milestones@main
+```
+
+## Create milestone
+Create a new GitHub milestone, where the first word is the version tag name for the release you will be publishing.
+
+For example: `v0.1.0 Test 🧪` -> `v0.1.0`
+
+!!! abstract "Naming conventions"
+
+    The milestone name can contain emojis and other markdown characters, but the tag name must only contain alphanumeric symbols.
+
+## Close milestone
+Close a GitHub milestone, then look in the "Releases" section of your repository. There should be a new draft at the top of the page with
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -0,0 +1,84 @@
+site_name: milestones
+site_description: Github actions for creating new milestones
+site_url: https://quaternionmedia.github.io/milestones
+repo_url: https://github.com/quaternionmedia/milestones/
+
+nav:
+  - Home: index.md
+  - Usage: usage.md
+
+markdown_extensions:
+  - admonition
+  - def_list
+  - footnotes
+  - md_in_html
+  - meta
+  - pymdownx.caret
+  - pymdownx.details
+  - pymdownx.emoji:
+      emoji_index: !!python/name:materialx.emoji.twemoji
+      emoji_generator: !!python/name:materialx.emoji.to_svg
+  - pymdownx.highlight
+  - pymdownx.inlinehilite
+  - pymdownx.keys
+  - pymdownx.mark
+  - pymdownx.snippets
+  - pymdownx.superfences:
+      custom_fences:
+        - name: mermaid
+          class: mermaid
+          format: !!python/name:pymdownx.superfences.fence_code_format
+  - pymdownx.tabbed:
+      alternate_style: true
+  - pymdownx.tasklist:
+      custom_checkbox: true
+  - pymdownx.tilde
+  - tables
+  - toc:
+      permalink: true
+      toc_depth: 4
+
+theme:
+  name: material
+  palette:
+    - media: '(prefers-color-scheme: dark)'
+      scheme: slate
+      toggle:
+        icon: material/toggle-switch
+        name: Switch to light mode
+    - media: '(prefers-color-scheme: light)'
+      scheme: default
+      toggle:
+        icon: material/toggle-switch-off-outline
+        name: Switch to dark mode
+  features:
+    - content.code.annotate # Enable code annotations for a specific block
+    - header.autohide # Hide header when scrolling
+    - navigation.instant # Load requests with XHR without reloading page
+    - navigation.sections # Top level sections rendered as group in sidebar
+    - navigation.tabs # Top level sections rendered as navbar
+    - navigation.tabs.sticky # Tabs visible on scroll
+    - navigation.top # Back to top button
+    - navigation.tracking # Adds url#anchor to address bar
+    - navigation.expand # Expand all collapsed sections by default
+    - toc.integrate # Nav bar is always rendered on the left
+    - search.highlight # Highlight occurances in result when searching for a term
+    - search.suggest # Suggest results in search
+  custom_dir: overrides
+
+plugins:
+  - search
+  - git-revision-date-localized:
+      type: timeago
+      enable_creation_date: true
+
+extra:
+  social:
+    - name: Quaternion Media
+      icon: material/web
+      link: https://quaternion.media
+    - name: GitHub repository
+      icon: fontawesome/brands/github
+      link: https://github.com/quaternionmedia/milestones/
+  version:
+    provider: mike
diff --git a/overrides/main.html b/overrides/main.html
@@ -0,0 +1,8 @@
+{% extends "base.html" %}
+
+{% block outdated %}
+  You're not viewing the latest version.
+  <a href="{{ '../' ~ base_url }}">
+    <strong>Click here to go to latest.</strong>
+  </a>
+{% endblock %}