From 2a62eab3a24944f53fd648c9dc0cc02c0ee1f056 Mon Sep 17 00:00:00 2001 From: Thorsten Klein Date: Wed, 8 Sep 2021 14:46:32 +0200 Subject: [PATCH] docs: use mike and gh actions for versioned k3d.io (#731) * docs: use mike for versioned k3d.io * switch to ghactions for docs --- .drone.yml | 65 ++++++++++++-------------------------- .github/workflows/docs.yml | 46 +++++++++++++++++++++++++++ docs/requirements.txt | 15 +++++---- mkdocs.yml | 17 ++++++++-- 4 files changed, 89 insertions(+), 54 deletions(-) create mode 100644 .github/workflows/docs.yml diff --git a/.drone.yml b/.drone.yml index f37c98c1..22486993 100644 --- a/.drone.yml +++ b/.drone.yml @@ -73,6 +73,7 @@ steps: - tag ref: include: + # include only pre-release tags - "refs/tags/*rc*" - "refs/tags/*beta*" - "refs/tags/*alpha*" @@ -97,11 +98,14 @@ steps: - tag ref: exclude: + # exclude pre-release tags - "refs/tags/*rc*" - "refs/tags/*beta*" - "refs/tags/*alpha*" - "refs/tags/*test*" - "refs/tags/*dev*" + # exclude docs specific tags + - "refs/tags/*docs*" services: # Starting the docker service to be used by dind @@ -116,51 +120,6 @@ volumes: - name: dockersock temp: {} ---- -######################### -##### Documentation ##### -######################### - -kind: pipeline -type: docker -name: docs - -platform: - os: linux - arch: amd64 - -steps: - - - name: build - image: python:3.9 - commands: - - python3 -m pip install -r docs/requirements.txt - - mkdocs build --verbose --clean --strict - when: - branch: - - main - event: - - push - - - name: publish - image: plugins/gh-pages - settings: - password: - from_secret: github_token - username: rancherio-gh-m - pages_directory: site/ - target_branch: gh-pages - when: - branch: - - main - event: - - push - -trigger: - event: - - push - branch: - - main --- ########################### @@ -258,6 +217,10 @@ trigger: event: - tag # see note at the start of the "Docker Images" section: creates SemVer tagged images using the `auto_tag` option of the docker plugin - push # `auto_tag` option only creates the `latest` tag if target branch is default branch (i.e. `main`) + ref: + exclude: + # exclude docs specific tags + - "refs/tags/*docs*" depends_on: - main @@ -310,6 +273,10 @@ trigger: event: - tag # see note at the start of the "Docker Images" section: creates SemVer tagged images using the `auto_tag` option of the docker plugin - push # `auto_tag` option only creates the `latest` tag if target branch is default branch (i.e. `main`) + ref: + exclude: + # exclude docs specific tags + - "refs/tags/*docs*" depends_on: - main @@ -399,6 +366,10 @@ trigger: event: - tag # see note at the start of the "Docker Images" section: creates SemVer tagged images using the `auto_tag` option of the docker plugin - push # `auto_tag` option only creates the `latest` tag if target branch is default branch (i.e. `main`) + ref: + exclude: + # exclude docs specific tags + - "refs/tags/*docs*" depends_on: - main @@ -465,6 +436,10 @@ trigger: event: - tag # see note at the start of the "Docker Images" section: creates SemVer tagged images using the `auto_tag` option of the manifest plugin - push # `auto_tag` option only creates the `latest` tag if target branch is default branch (i.e. `main`) + ref: + exclude: + # exclude docs specific tags + - "refs/tags/*docs*" depends_on: - main diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 00000000..1a23f78a --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,46 @@ +name: k3d.io + +on: + push: + branches: + - main + tags: + # only run on tags for real releases and special docs releases + - 'v[0-9]+.[0-9]+.[0-9]+' + - 'v[0-9]+.[0-9]+.[0-9]+-docs.[0-9]+' + # tags-ignore: + # - "*rc*" + # - "*beta*" + # - "*alpha*" + # - "*test*" + # - "*dev*" + +jobs: + build: + runs-on: ubuntu-20.04 + container: + image: python:3.9 + steps: + - name: Checkout Project + uses: actions/checkout@v2 + with: + fetch-depth: 0 + - name: Install Requirements + run: pip install -r docs/requirements.txt + - name: Build with MkDocs (validation) + run: | + mkdocs build --verbose --clean --strict + rm -r site/ + - name: Configure Git + if: startsWith(github.ref, 'refs/tags/') + id: git + run: | + git config --global user.name ghaction-k3d.io + git config --global user.email ghaction@k3d.io + echo ::set-output name=tag::${GITHUB_REF#refs/tags/} + - name: Build & Deploy with Mike (versioned) + if: startsWith(github.ref, 'refs/tags/') + run: | + mike deploy --update-aliases --push --rebase ${{ steps.git.outputs.tag }} stable + + diff --git a/docs/requirements.txt b/docs/requirements.txt index 79082186..acf32eed 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,7 +1,8 @@ -mkdocs -mkdocs-material -pymdown-extensions -mkdocs-git-revision-date-localized-plugin -mkdocs-awesome-pages-plugin -mdx_truly_sane_lists -mkdocs-include-markdown-plugin # https://github.com/mondeja/mkdocs-include-markdown-plugin \ No newline at end of file +mkdocs==1.2.2 +mkdocs-material==7.2.6 +pymdown-extensions==8.2 +mkdocs-git-revision-date-localized-plugin==0.9.3 +mkdocs-awesome-pages-plugin==2.5.0 +mdx_truly_sane_lists==1.2 # https://github.com/radude/mdx_truly_sane_lists +mkdocs-include-markdown-plugin==3.2.2 # https://github.com/mondeja/mkdocs-include-markdown-plugin +mike==1.1.0 # versioned docs: https://github.com/jimporter/mike diff --git a/mkdocs.yml b/mkdocs.yml index 36079707..150892af 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -25,7 +25,10 @@ theme: name: material language: en features: - - tabs + - navigation.top # show back to top button + - search.suggest # search suggestions: https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-search/#search-suggestions + - search.highlight # highlight search term on target page: https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-search/#search-suggestions + palette: - media: "(prefers-color-scheme: light)" scheme: default @@ -71,6 +74,16 @@ plugins: type: date - awesome-pages # https://squidfunk.github.io/mkdocs-material/plugins/awesome-pages/ - include-markdown # https://github.com/mondeja/mkdocs-include-markdown-plugin + - mike: # Versioned Docs: https://github.com/jimporter/mike + version_selector: true # set to false to leave out the version selector + css_dir: static/css # the directory to put the version selector's CSS + javascript_dir: static/js # the directory to put the version selector's JS + canonical_version: null # the version for ; `null` uses the version specified via `mike deploy` + +# Extra mkdocs-material settings +extra: + version: + provider: mike # Other Settings -strict: true # halt processing when a warning is raised \ No newline at end of file +strict: true # halt processing when a warning is raised