From a24fe286d119a05e6bbeaf4d1dcd78f9e925bcc5 Mon Sep 17 00:00:00 2001 From: Harpo Date: Sun, 2 Apr 2023 11:23:04 -0700 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9A=20Docs=20(#23)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * 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 --- .github/workflows/docs.yml | 36 ++++++++++++++++ docs/index.md | 10 +++++ docs/usage.md | 33 +++++++++++++++ mkdocs.yml | 84 ++++++++++++++++++++++++++++++++++++++ overrides/main.html | 8 ++++ 5 files changed, 171 insertions(+) create mode 100644 .github/workflows/docs.yml create mode 100644 docs/index.md create mode 100644 docs/usage.md create mode 100644 mkdocs.yml create mode 100644 overrides/main.html diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 0000000..dc84cf3 --- /dev/null +++ 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 new file mode 100644 index 0000000..d31af92 --- /dev/null +++ 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 new file mode 100644 index 0000000..b5b8378 --- /dev/null +++ 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 new file mode 100644 index 0000000..a1d9e40 --- /dev/null +++ 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 new file mode 100644 index 0000000..0af326a --- /dev/null +++ b/overrides/main.html @@ -0,0 +1,8 @@ +{% extends "base.html" %} + +{% block outdated %} + You're not viewing the latest version. + + Click here to go to latest. + +{% endblock %}