Migrate documentation to github pages (vagrant-libvirt#1523)

Switch from having all documentation contained within the README to
publishing a jekyll static site of documentation under github pages.

This allows for configuration and installation guides to be handled
separately to make for the relevant pieces to be in smaller chunks and
therefore easier to follow for users. Additionally a table of contents
can now be included in a left navigation section that ensures it should
be possible to quickly jump from the start to any section and back
again.

Include support for publishing previews and releases under separate
directories to allow for them to exist at the same time as the other
latest version of the documents.

The navigation section also includes support for accessing any of the
other versions published so that it easier to see what configuration
options exist for a given release. These will be published automatically
when releases are added.

.github/workflows/publish-documentation-preview-notify.yml

@@ -0,0 +1,25 @@
+name: Deploy Docs Preview Requires Label
+on:
+  pull_request_target:
+    types:
+      - opened
+      - reopened
+      - synchronized
+    paths:
+      - 'docs/**'
+
+permissions:
+  pull-requests: write
+jobs:
+  notify-label-required:
+    if: ${{ !contains(github.event.pull_request.labels.*.name, 'preview-docs') }}
+    runs-on: ubuntu-latest
+    steps:
+    - name: Comment on label required for docs preview deploy
+      uses: marocchino/sticky-pull-request-comment@v2
+      with:
+        recreate: true
+        header: notify-label-required
+        message: |-
+          Maintainers: This PR updates the documentation, please review and apply
+          the label 'preview-docs' if satisfied it is safe to publish.

.github/workflows/publish-documentation-preview.yml

@@ -0,0 +1,72 @@
+name: Deploy Docs Preview
+on:
+  pull_request_target:
+    types:
+      - closed
+      - labeled
+    paths:
+      - 'docs/**'
+
+permissions:
+  contents: write
+  pull-requests: write
+jobs:
+  build-and-deploy:
+    if: ${{ github.event.action == 'closed' || (github.event.action == 'labeled' && github.event.label.name == 'preview-docs') }}
+    concurrency: publish-gh-pages
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout 🛎️
+        uses: actions/checkout@v3
+        with:
+          ref: ${{ github.event.pull_request.head.sha }}
+      - name: Set up Ruby
+        if: ${{ github.event.action == 'labeled' }}
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: 2.6
+      - name: Install and Build 🔧
+        # don't allow a close to execute anything from the source code
+        if: ${{ github.event.action == 'labeled' }}
+        run: |
+          PR_NUMBER=$(jq -r ".number" "$GITHUB_EVENT_PATH")
+          REPO_NAME=$(jq -r ".repository.name" "$GITHUB_EVENT_PATH")
+
+          # TODO find a way for jekyll to perform this automatically
+          convert docs/_assets/images/logo.png -define icon:auto-resize=256,64,48,32,16 docs/favicon.ico
+
+          # avoid look up of API as it doesn't work from within actions without exposing the GITHUB_TOKEN here which is a security risk
+          cat <<EOF >> docs/_config.yml
+          repository_nwo: vagrant-libvirt/vagrant-libvirt
+          EOF
+
+          BUNDLE_GEMFILE=./docs/Gemfile bundle install
+          BUNDLE_GEMFILE=./docs/Gemfile bundle exec jekyll build --source docs/ --baseurl="/${REPO_NAME}/pr-preview/pr-${PR_NUMBER}" --destination build
+      - name: Set action
+        run: |
+          event_type=$(jq -r ".action" "$GITHUB_EVENT_PATH")
+          echo "event_type is $event_type"
+
+          case $event_type in
+            "labeled")
+              echo "action=deploy" >> "$GITHUB_ENV"
+              ;;
+            "closed")
+              echo "action=remove" >> "$GITHUB_ENV"
+              ;;
+            *)
+              echo "unknown event type $event_type; no action to take"
+              echo "action=none" >> "$GITHUB_ENV"
+              ;;
+          esac
+      - name: Deploy preview
+        uses: rossjrw/pr-preview-action@v1
+        with:
+          source-dir: ./build/
+          preview-branch: gh-pages
+          umbrella-dir: pr-preview
+      - name: Remove label
+        uses: actions-ecosystem/action-remove-labels@v1
+        if: ${{ always() }}
+        with:
+          labels: preview-docs

.github/workflows/publish-documentation-release.yml

@@ -0,0 +1,46 @@
+name: Deploy Docs Release
+on:
+  push:
+    tags:
+      - '*.*.*'
+
+permissions:
+  contents: write
+
+jobs:
+  build-and-deploy:
+    concurrency: ci-${{ github.ref }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout 🛎️
+        uses: actions/checkout@v3
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: 2.6
+      - name: Install and Build 🔧
+        run: |
+          VERSION={{ github.ref_name }}
+          REPO_NAME=$(jq -r ".repository.name" "$GITHUB_EVENT_PATH")
+
+          # TODO find a way for jekyll to perform this automatically
+          convert docs/_assets/images/logo.png -define icon:auto-resize=256,64,48,32,16 docs/favicon.ico
+
+          # avoid look up of API as it doesn't work from within actions without exposing the GITHUB_TOKEN here which is a security risk
+          cat <<EOF >> docs/_config.yml
+          repository_nwo: vagrant-libvirt/vagrant-libvirt
+          EOF
+
+          BUNDLE_GEMFILE=./docs/Gemfile bundle install
+          BUNDLE_GEMFILE=./docs/Gemfile bundle exec jekyll build --source docs/ --baseurl="/${REPO_NAME}/version/${VERSION}" --destination build
+      - name: Deploy 🚀
+        uses: JamesIves/[email protected]
+        with:
+          branch: gh-pages
+          folder: build
+          clean: true
+          force: false
+          target-folder: version/{{ github.ref_name }}
+          clean-exclude: |
+            pr-preview/
+            version/

.github/workflows/publish-documentation.yml

@@ -0,0 +1,43 @@
+name: Deploy Docs
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'docs/**'
+
+permissions:
+  contents: write
+
+jobs:
+  build-and-deploy:
+    concurrency: ci-${{ github.ref }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout 🛎️
+        uses: actions/checkout@v3
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: 2.6
+      - name: Install and Build 🔧
+        run: |
+          # TODO find a way for jekyll to perform this automatically
+          convert docs/_assets/images/logo.png -define icon:auto-resize=256,64,48,32,16 docs/favicon.ico
+
+          # avoid look up of API as it doesn't work from within actions without exposing the GITHUB_TOKEN here which is a security risk
+          cat <<EOF >> docs/_config.yml
+          repository_nwo: vagrant-libvirt/vagrant-libvirt
+          EOF
+
+          BUNDLE_GEMFILE=./docs/Gemfile bundle install
+          BUNDLE_GEMFILE=./docs/Gemfile bundle exec jekyll build --source docs/ --destination build
+      - name: Deploy 🚀
+        uses: JamesIves/[email protected]
+        with:
+          branch: gh-pages
+          folder: build
+          clean: true
+          clean-exclude: |
+            pr-preview/
+            version/

.gitignore

@@ -20,6 +20,7 @@ tmp
 .vagrant
 *.swp
 .deps
+docs/favicon.ico
 
 # don't commit the generated version
 lib/vagrant-libvirt/version