Repository: obriencj/koji-smoky-dingo (language: python)

Issue:
build and deploy docs at release via action
author a new github action workflow which will checkout the release ref, build docs, and deploy them to gh-pages.

set the project configuration to allow pages to be deployed via action

remove the Makefile method afterwards, and drop the gh-pages branch and submodule


Discussion / hints:

Fix patch:
diff --git a/.github/workflows/build_docs.yml b/.github/workflows/build_docs.yml
new file mode 100644
index 00000000..f1dee263
--- /dev/null
+++ b/.github/workflows/build_docs.yml
@@ -0,0 +1,42 @@
+name: "Build: Documentation"
+
+
+on:
+  workflow_dispatch:
+  workflow_call:
+
+
+jobs:
+
+  build-documentation:
+    runs-on: ubuntu-latest
+
+    strategy:
+      fail-fast: true
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+
+      - name: Setup Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: 3.9
+
+      - name: Install Dependencies
+        run: |
+          sudo apt-get install make pandoc
+          pip install tox tox-gh-actions
+
+      - name: Generate Documentation
+        run: |
+          make docs
+
+      - name: Store Documentation
+        uses: actions/upload-pages-artifact@v2
+        with:
+          path:
+            build/sphinx/dirhtml
+
+
+# The end.
diff --git a/.github/workflows/rpms.yml b/.github/workflows/build_rpms.yml
similarity index 94%
rename from .github/workflows/rpms.yml
rename to .github/workflows/build_rpms.yml
index 2e2acfbe..0ca70aef 100644
--- a/.github/workflows/rpms.yml
+++ b/.github/workflows/build_rpms.yml
@@ -1,5 +1,4 @@
-
-name: RPM Build
+name: "Build: RPMs"
 
 
 on:
@@ -8,6 +7,7 @@ on:
 
 
 jobs:
+
   build-srpm:
     runs-on: ubuntu-latest
 
@@ -82,11 +82,11 @@ jobs:
         run: |
           make archive
 
-      - name: Generate ${{ matrix.platform }} RPM
+      - name: Generate RPM ${{ matrix.platform }}
         run: |
           tools/launch-build.sh ${{ matrix.platform }}
 
-      - name: Store ${{ matrix.platform }} RPM
+      - name: Store RPM ${{ matrix.platform }}
         uses: actions/upload-artifact@v3
         with:
           name: RPMs
diff --git a/.github/workflows/wheel.yml b/.github/workflows/build_wheel.yml
similarity index 92%
rename from .github/workflows/wheel.yml
rename to .github/workflows/build_wheel.yml
index dc24e281..4bf3cbc3 100644
--- a/.github/workflows/wheel.yml
+++ b/.github/workflows/build_wheel.yml
@@ -1,5 +1,4 @@
-
-name: Wheel Build
+name: "Build: Wheel"
 
 
 on:
@@ -8,6 +7,7 @@ on:
 
 
 jobs:
+
   build-wheel:
     runs-on: ubuntu-latest
 
@@ -27,7 +27,7 @@ jobs:
         run: |
           pip install build
 
-      - name: Build Wheel
+      - name: Generate Wheel
         run: |
           python -B -m build .
 
diff --git a/.github/workflows/on_push.yml b/.github/workflows/on_push.yml
new file mode 100644
index 00000000..1b1d0aa8
--- /dev/null
+++ b/.github/workflows/on_push.yml
@@ -0,0 +1,42 @@
+name: "Trigger: on Push/PR"
+
+
+on:
+  workflow_dispatch:
+
+  push:
+    branches:
+      - master
+    ignore-paths:
+      - 'docs/**'
+      - 'examples/**'
+      - 'tools/**'
+    paths:
+      - 'setup.cfg'
+      - '**/*.py'
+      - '**/*.pyi'
+      - '.github/workflows/run_bandit.yml'
+      - '.github/workflows/run_tests.yml'
+
+  pull_request:
+    ignore-paths:
+      - 'docs/**'
+      - 'examples/**'
+      - 'tools/**'
+    paths:
+      - 'setup.cfg'
+      - '**/*.py'
+      - '**/*.pyi'
+      - '.github/workflows/run_bandit.yml'
+      - '.github/workflows/run_tests.yml'
+
+
+jobs:
+  run-bandit:
+    uses: ./.github/workflows/run_bandit.yml
+
+  run-tests:
+    uses: ./.github/workflows/run_tests.yml
+
+
+# The end.
diff --git a/.github/workflows/release.yml b/.github/workflows/on_release.yml
similarity index 78%
rename from .github/workflows/release.yml
rename to .github/workflows/on_release.yml
index 8ab920d6..a0316acd 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/on_release.yml
@@ -1,9 +1,4 @@
-# Github Action definition for publishing assets to the release and to
-# PyPI when a release is tagged. Also emits a notification post to
-# mastodon
-
-
-name: Release Assets
+name: "Trigger: on Release"
 
 
 on:
@@ -54,15 +49,16 @@ jobs:
           path: release.md
 
   build-wheel:
-    name: Trigger Wheel build
-    uses: ./.github/workflows/wheel.yml
+    uses: ./.github/workflows/build_wheel.yml
 
   build-rpms:
-    name: Trigger RPM builds
-    uses: ./.github/workflows/rpms.yml
+    uses: ./.github/workflows/build_rpms.yml
+
+  build-docs:
+    uses: ./.github/workflows/build_docs.yml
 
-  attach-assets:
-    name: Attach Assets to Release
+  deploy-release:
+    name: Deploy assets to release
     runs-on: ubuntu-latest
 
     permissions:
@@ -74,9 +70,6 @@ jobs:
       - build-rpms
 
     steps:
-      - name: Checkout
-        uses: actions/checkout@v3
-
       - name: Install Dependencies
         run: |
           sudo apt-get install hub
@@ -102,6 +95,8 @@ jobs:
         run: |
           gh release edit ${{ github.ref_name }} \
             -F release.md
+        env:
+          GITHUB_TOKEN: ${{ github.TOKEN }}
 
       - name: Upload python dist content
         run: |
@@ -110,7 +105,27 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ github.TOKEN }}
 
-  pypi:
+  deploy-docs:
+    name: Deploy documentation
+    runs-on: ubuntu-latest
+
+    needs:
+      - build-docs
+
+    permissions:
+      pages: write
+      id-token: write
+
+    environment:
+      name: github-pages
+      url: ${{ steps.deploy.outputs.page_url }}
+
+    steps:
+      - name: Deploy site
+        id: deploy
+        uses: actions/deploy-pages@v2
+
+  deploy-pypi:
     name: Upload release to PyPI
     runs-on: ubuntu-latest
 
@@ -139,13 +154,11 @@ jobs:
     runs-on: ubuntu-latest
 
     needs:
-      - attach-assets
-      - pypi
+      - deploy-release
+      - deploy-docs
+      - deploy-pypi
 
     steps:
-      - name: Checkout
-        uses: actions/checkout@v3
-
       - name: Fetch python dist content
         uses: actions/download-artifact@v3
         with:
@@ -159,10 +172,8 @@ jobs:
         run: |
           echo "RELEASE_DATE=$(date +'%Y-%m-%d')" >> "$GITHUB_ENV"
 
-      - name: "\
-        Trigger announcement for ${{ env.DIST_VERSION }}(tag
-        ${{ github.ref_name }}) on ${{ env.RELEASE_DATE }}"
-        uses: ./.github/workflows/announce.yml
+      - name: Post announcement
+        uses: ./.github/workflows/run_announce.yml
         with:
           version: ${{ env.DIST_VERSION }}
           date: ${{ env.RELEASE_DATE }}
diff --git a/.github/workflows/announce.yml b/.github/workflows/run_announce.yml
similarity index 84%
rename from .github/workflows/announce.yml
rename to .github/workflows/run_announce.yml
index 482e2fb7..337cebb0 100644
--- a/.github/workflows/announce.yml
+++ b/.github/workflows/run_announce.yml
@@ -1,13 +1,8 @@
-# Github Action definition for creating a mastodon release for this
-# project.
-
-
-name: Announce Release
+name: "Run: Announcement"
 
 
 on:
   workflow_call:
-    # shame github actions parses yaml with anchors disabled
     inputs:
       version:
         description: package version to announce
@@ -43,7 +38,6 @@ on:
 
 
 jobs:
-
   announce:
     name: Announce release to @obriencj@fosstodon.org
     runs-on: ubuntu-latest
@@ -56,12 +50,16 @@ jobs:
           access-token: ${{ secrets.MASTODON_ACCESS_TOKEN }}
 
           message: "\
-          Version ${{ inputs.version }} of koji-smoky-dingo was
+          koji-smoky-dingo ${{ inputs.version }} was
           released on ${{ inputs.date }}
 
+
+          View the release on GitHub:
+
           https://github.com/obriencj/koji-smoky-dingo/releases/tag/\
           ${{ inputs.ref }}
 
+
           #koji #kojismokydingo"
 
 
diff --git a/.github/workflows/bandit.yml b/.github/workflows/run_bandit.yml
similarity index 51%
rename from .github/workflows/bandit.yml
rename to .github/workflows/run_bandit.yml
index d1a3783b..69be4dd0 100644
--- a/.github/workflows/bandit.yml
+++ b/.github/workflows/run_bandit.yml
@@ -1,34 +1,9 @@
-# Github Action definitions for running a Bandit scan and storing the
-# results in the security tab
-
-
-name: Bandit
+name: "Run: Bandit Scan"
 
 
 on:
-  push:
-    branches:
-      - master
-    ignore-paths:
-      - 'docs/**'
-      - 'examples/**'
-      - 'tools/**'
-    paths:
-      - 'setup.cfg'
-      - '**/*.py'
-      - '**/*.pyi'
-      - '.github/workflows/bandit.yml'
-
-  pull_request:
-    ignore-paths:
-      - 'docs/**'
-      - 'examples/**'
-      - 'tools/**'
-    paths:
-      - 'setup.cfg'
-      - '**/*.py'
-      - '**/*.pyi'
-      - '.github/workflows/bandit.yml'
+  workflow_call:
+  workflow_dispatch:
 
 
 jobs:
@@ -42,7 +17,7 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v3
 
-      - name: Set up Python
+      - name: Setup Python
         uses: actions/setup-python@v4
         with:
           python-version: 3.9
diff --git a/.gitmodules b/.gitmodules
index 73f0603e..e69de29b 100644
--- a/.gitmodules
+++ b/.gitmodules
@@ -1,6 +0,0 @@
-[submodule "gh-pages"]
-path = gh-pages
-url = https://github.com/obriencj/koji-smoky-dingo.git
-# pushurl = git@github.com:obriencj/koji-smoky-dingo.git
-branch = gh-pages
-
diff --git a/Makefile b/Makefile
index 0f46b49a..67847989 100644
--- a/Makefile
+++ b/Makefile
@@ -152,30 +152,6 @@ docs/overview.rst: README.md
 	rm -f overview.md
 
 
-pull-docs: requires-git	## Refreshes the gh-pages submodule
-	@git submodule init
-	@git submodule update --remote gh-pages
-
-
-stage-docs: docs pull-docs	## Builds docs and stages them in gh-pages
-	@pushd gh-pages >/dev/null && \
-	rm -rf * && \
-	touch .nojekyll ; \
-	popd >/dev/null ; \
-	cp -vr build/sphinx/dirhtml/* gh-pages/
-
-
-deploy-docs: stage-docs requires-git	## Builds, stages, and deploys docs to gh-pages
-	@pushd gh-pages >/dev/null && \
-	git remote set-url --push origin $(ORIGIN_PUSH) ; \
-	git add -A && git commit -m "deploying sphinx update" && git push ; \
-	popd >/dev/null ; \
-	if [ `git diff --name-only gh-pages` ] ; then \
-		git add gh-pages ; \
-		git commit -m "docs deploy [ci skip]" -o gh-pages ; \
-	fi
-
-
 clean-docs:	## Remove built docs
 	@rm -rf build/sphinx/*
 
diff --git a/docs/overview.rst b/docs/overview.rst
index 37ff834c..c4979927 100644
--- a/docs/overview.rst
+++ b/docs/overview.rst
@@ -26,9 +26,7 @@ Tag Commands
 ------------
 
 These commands modify tag features, requiring either the tag permission
-(koji >=
-`1.18 <https://docs.pagure.org/koji/release_notes/release_notes_1.18/>`__)
-or the admin permission.
+(koji >= [1.18]) or the admin permission.
 
 +----------------------------+-----------------------------------------+
 | Command                    | Description                             |
@@ -154,56 +152,45 @@ included spec to produce an RPM and install that.
 .. code:: bash
 
    make clean rpm
-   dnf install dist/noarch/python3-kojismokydingo-2.1.0-1.fc38.noarch.rpm
+   dnf install dist/noarch/python3-kojismokydingo-2.2.0-0.fc38.noarch.rpm
 
 As a System-wide Wheel via Pip
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Using traditional setuptools or pip installation methods can also
-achieve this by specifying the specific root or prefix parameter
+The pip3 tool can also achieve this by specifying the specific root or
+prefix parameter
 
 .. code:: bash
 
-   python3 setup.py bdist_wheel
-   pip3 install --prefix /usr -I dist/kojismokydingo-2.1.0-py3-none-any.whl
+   make clean build
+   pip3 install --prefix /usr -I dist/kojismokydingo-2.2.0-py3-none-any.whl
 
-As a User-only Wheel via Pip
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-However, if you only want the plugin available for yourself, you can
-install it anywhere and tell koji to look in that particular
-``site-package/koji_cli_plugins`` instance
+or you can install the most recent release straight from PyPI
 
 .. code:: bash
 
-   python3 setup.py bdist_wheel
-   pip3 install --user -I dist/kojismokydingo-2.1.0-py3-none-any.whl
+   pip3 install --prefix /usr -I kojismokydingo
 
-Additionally, you can install straight from PyPI
-
-.. code:: bash
-
-   pip3 install kojismokydingo --user
+As a User-only Wheel via Pip
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-And the following setting in ~/.koji/config assuming Python version 3.8
-– read the output of the install command above to verify your install
-path. Note that the section title needs to match your koji profile, and
-that you need to configure this setting for each profile you’ll want to
-use the meta plugin with.
+If you only want the plugin available for yourself, you can use the
+``install`` target of the Makefile to easily build the wheel, install it
+using pip3, then symlink the meta plugin into your koji user plugins
+directory.
 
-::
+.. code:: bash
 
-   [koji]
-   plugin_paths = ~/.local/lib/python3.8/site-packages/koji_cli_plugins/
+   make clean install
 
-With koji >=
-`1.18 <https://docs.pagure.org/koji/release_notes/release_notes_1.18/>`__,
-the meta plugin can also be symlinked into ``~/.koji/plugins``
+or you can install the most recent release straight from PyPI, and then
+copy the meta plugin into place
 
 .. code:: bash
 
+   pip3 install --user -I kojismokydingo
    mkdir -p ~/.koji/plugins
-   ln -s ~/.local/lib/python$(python3 -c 'import sys; print("{}.{}".format(*sys.version_info))')/site-packages/koji_cli_plugins/kojismokydingometa.py ~/.koji/plugins
+   cp $(python3 -c 'import koji_cli_plugins.kojismokydingometa as k ; print(k.__file__);' ~/.koji/plugins
 
 Contact
 -------
diff --git a/gh-pages b/gh-pages
deleted file mode 160000
index 82bbffb5..00000000
--- a/gh-pages
+++ /dev/null
@@ -1,1 +0,0 @@
-Subproject commit 82bbffb58673b308b5415b4bd0a3a87323bc8367


Test patch:
diff --git a/.github/workflows/tox.yml b/.github/workflows/run_tests.yml
similarity index 75%
rename from .github/workflows/tox.yml
rename to .github/workflows/run_tests.yml
index b7a3d0a7..79e5d5a2 100644
--- a/.github/workflows/tox.yml
+++ b/.github/workflows/run_tests.yml
@@ -1,39 +1,10 @@
-# Github Action definition for running tox across the supported python
-# versions. Intended to be triggered on push to master and on filing
-# of a pull_request, when those pushes hit something that impacts the
-# running of the tests.
-
-
-name: Tox
+name: "Run: Unit Tests"
 
 
 on:
+  workflow_call:
   workflow_dispatch:
 
-  push:
-    branches:
-      - master
-    ignore-paths:
-      - 'docs/**'
-      - 'examples/**'
-      - 'tools/**'
-    paths:
-      - 'setup.cfg'
-      - '**/*.py'
-      - '**/*.pyi'
-      - '.github/workflows/tox.yml'
-
-  pull_request:
-    ignore-paths:
-      - 'docs/**'
-      - 'examples/**'
-      - 'tools/**'
-    paths:
-      - 'setup.cfg'
-      - '**/*.py'
-      - '**/*.pyi'
-      - '.github/workflows/tox.yml'
-
 
 jobs:
   pre-tests:
@@ -46,7 +17,7 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v3
 
-      - name: Set up Python
+      - name: Setup Python
         uses: actions/setup-python@v4
         with:
           python-version: 3.9