Fixes #73 CI/CD: Write release GH Action: publish docs

.github/workflows/publish-docs.yml

@@ -0,0 +1,77 @@
+name: Publish docs to GitHub pages
+
+on:
+  create:
+    branches:
+      - 'docs/**'
+  push:
+    branches:
+      - 'docs/**'
+    paths:
+      - 'docs/**'
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: [3.7]
+        package: [docs]
+
+    steps:
+      - uses: actions/checkout@v2
+        with:
+          # Only a single commit is fetched by default, for the ref/SHA that triggered the workflow.
+          # Set fetch-depth: 0 to fetch all history for all branches and tags.
+          fetch-depth: 0
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v2
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Set the current branch environment variable
+        working-directory: ${{ matrix.package }}
+        run: |
+          CURRENT_BRANCH_VAR=${GITHUB_REF#refs/heads/}
+          echo "Current branch: $CURRENT_BRANCH_VAR"
+          # Set CURRENT_BRANCH environment variable to the current branch name.
+          echo "::set-env name=CURRENT_BRANCH::$(echo $CURRENT_BRANCH_VAR)"
+      - name: Display all remote branches
+        working-directory: ${{ matrix.package }}
+        run: |
+          # Display all remote branches
+          git branch -r
+      - name: Set the latest docs branch environment variable
+        working-directory: ${{ matrix.package }}
+        run: |
+          # Get only docs branches, extract the "docs/x.y.z" part, sort them in descending order, and get the first one.
+          LATEST_DOCS_BRANCH_VAR=$(git branch -r | grep -e ".*\/*docs\/[0-9].[0-9].[0-9]" | sed -n "s/.*\/*\(docs\/[0-9].[0-9].[0-9]\).*/\1/p" | sort -r | head -n 1)
+          echo "Latest docs branch: $LATEST_DOCS_BRANCH_VAR"
+          # Set the LATEST_DOCS_BRANCH environment variable.
+          echo "::set-env name=LATEST_DOCS_BRANCH::$(echo $LATEST_DOCS_BRANCH_VAR)"
+      - name: Check that the current branch is the latest docs branch, fail otherwise
+        working-directory: ${{ matrix.package }}
+        run: |
+          if [ $CURRENT_BRANCH != $LATEST_DOCS_BRANCH ]; then
+            echo "The action is running on branch $CURRENT_BRANCH which is not the latest docs branch ($LATEST_DOCS_BRANCH)."
+            exit 1
+          else
+            echo "The action is running on the latest docs branch."
+          fi
+      - name: Install Pipenv
+        uses: dschep/install-pipenv-action@v1
+      - name: Install dependencies for building documenation
+        working-directory: ${{ matrix.package }}
+        run: |
+          pipenv install
+      - name: Build documentation
+        working-directory: ${{ matrix.package }}
+        run: |
+          pipenv run mkdocs build --clean
+      - name: Deploy the contents of docs/site to gh-pages 🚀
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: docs/site
+          commit_message: Deploy to gh-pages 🚀
+          user_name: "github-actions[bot]"
+          user_email: "github-actions[bot]@users.noreply.github.com"

docs/Pipfile

@@ -4,9 +4,12 @@ verify_ssl = true
 name = "pypi"
 
 [packages]
-mkdocs = "*"
-mkdocs-material = "*"
-markdown-include = "*"
-mkdocs-awesome-pages-plugin = "*"
+mkdocs = "==0.17.5"
+mkdocs-material = "==2.9.2"
+markdown-include = "==0.5.1"
+mkdocs-awesome-pages-plugin = "==1.2.0"
+
+[requires]
+python_version = "3.7"
 
 [dev-packages]

docs/readme.md

@@ -3,18 +3,14 @@
 This is the Markdown-based documentation for the Virtualization SDK.
 
 ## Local Testing
-Create a `virtualenv` using Python 3 and run `pipenv run mkdocs serve`
+Install dependencies for building documentation and run `pipenv run mkdocs serve`
 
 ```
-$ virtualenv -p /usr/local/bin/python3 .
-Running virtualenv with interpreter /usr/local/bin/python3
-Using base prefix '/usr/local/Cellar/python/3.7.2_1/Frameworks/Python.framework/Versions/3.7'
-New python executable in /Users/asarin/Documents/repos/virt-sdk-docs/env/bin/python3.7
-Also creating executable in /Users/asarin/Documents/repos/virt-sdk-docs/env/bin/python
-Installing setuptools, pip, wheel...
-done.
-
-$ source bin/activate
+$ pipenv install
+Installing dependencies from Pipfile.lock (cf5b7c)...
+  🐍   ▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉ 16/16 — 00:00:02
+To activate this project's virtualenv, run pipenv shell.
+Alternatively, run a command inside the virtualenv with pipenv run.
 
 $ pipenv run mkdocs serve
 INFO    -  Building documentation... 
@@ -89,6 +85,15 @@ This will generate the `site` directory which will contain all the gererated doc
 5. Go to your individual virtualization-sdk repo's settings, scroll to the bottom and verify under the GitHub Pages section the `Source` is set to `gh-pages branch`.
 6. Right above this will be a link explaining where your docs are published.
 
+You can also utilize the GitHub workflow for publishing docs (`.github/workflows/publish-docs.yml`) associated with a pull request. 
+The workflow is present on the `develop` branch. Create a branch called `docs/x.y.z` off `develop` on your fork of the repository
+to ensure that your docs branch triggers the workflow. If you have more than one `docs/x.y.z` branch in your fork,
+you have to push your doc changes to the docs branch with the latest `x.y.z` version. Otherwise, the workflow won't run.
+You also have to make sure to choose `gh-pages` branch on your fork as the [publishing source](https://help.github.com/en/github/working-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site#choosing-a-publishing-source).
+Once you push doc changes to the `docs/.x.y.z` branch, the docs site should be available under
+`<your-github-username>.github.io/virtualization-sdk` shortly after. You can see the status of publishing under 
+`https://github.com/<your-github-username>/virtualization-sdk/actions`. This is a fast way to give a preview of your
+changes in a pull request.
 
 ## Workflow diagrams
 We create workflow diagrams using a tool called `draw.io` which allows us to import/export diagrams in html format. If you want to add a diagram or edit an existing one, simply create or import the html file in `docs/References/html` into `draw.io` and make your desired changes. When you are done, select your diagram and export it as a png file. You can think of the html files as source code, and the png files as build artifacts. After this step, you will be prompted to crop what was selected. You'll want this box checked to trim the whitespace around the diagram. After the diagrams are exported, check in the updated html file to `docs/References/html` and png file to `docs/References/images`.