[NEW] v1.10.0 Policy-based CI/CD Pipeline

Cookiecutter Python Package v1.10.0 Release. In this Release, we enhance the CI/CD Pipeline configuration (file) produced out-of-the-box by the Generator, with Policy-based configurable Jobs: Docker, Docs, Code Vizualization (along with already-supporting-policies Lint Job).

CHANGELOG.rst

@@ -2,6 +2,43 @@
 Changelog
 =========
 
+1.10.0 (2023-12-24)
+===================
+
+*Upgrade*, **Docker**, **Code Visualization** and **Docs** *Jobs*, which are
+out-of-the-box produced by the `Generator` as part of the **CI/CD Pipeline**
+configuration YAML files, to be **Configurable by Policy**.
+
+*Design* a **High-Level** interface, for *configuring the CI/CD Behaviour*, allowing:
+- seemless switching between **Policies**, on a per-Job level
+- Easy **Override** to `"shutdown" Job"`, ie to *prevent upload*, by-passing `decision-making`
+- Easy **Override** to `"force Job"`, ie for *quick trial*, by-passing `decision-making`
+ governing desicion-making, on the Workflows/Jobs.
+
+A **Policy** governs how a Job behaves (ie if it should trigger), and each
+one yiels a *distinct* behaviour.
+
+At CI runtime, each Job uses its **Policy** and the Status of the Build,
+triggered on the CI, to decide if it should `run or not`.
+
+A Job can take into **account** "things" such as:
+- whether the current `Build` passed the `Test`'s
+- whether the `Test Job` was intentionally skipped
+- whether `production code` (ie python distro) changed from previous commit 
+
+Changes
+^^^^^^^
+
+feature
+"""""""
+- support **Policy-based** Workflows/Job, in the **CI/CD Pipeline**
+- add **Dev Guides** Page in Docs Website, when selecting `Mkdocs` as Docs Builder
+
+test
+""""
+- improve automatically derived emulated project to use for Post Hook Unit Tests
+
+
 1.9.0 (2023-12-22)
 ==================
 

README.rst

@@ -268,9 +268,9 @@ Free/Libre and Open Source Software (FLOSS)
 
 .. Github Releases & Tags
 
-.. |commits_since_specific_tag_on_master| image:: https://img.shields.io/github/commits-since/boromir674/cookiecutter-python-package/v1.9.0/master?color=blue&logo=github
+.. |commits_since_specific_tag_on_master| image:: https://img.shields.io/github/commits-since/boromir674/cookiecutter-python-package/v1.10.0/master?color=blue&logo=github
     :alt: GitHub commits since tagged version (branch)
-    :target: https://github.com/boromir674/cookiecutter-python-package/compare/v1.9.0..master
+    :target: https://github.com/boromir674/cookiecutter-python-package/compare/v1.10.0..master
 
 .. |commits_since_latest_github_release| image:: https://img.shields.io/github/commits-since/boromir674/cookiecutter-python-package/latest?color=blue&logo=semver&sort=semver
     :alt: GitHub commits since latest release (by SemVer)

docs/conf.py

@@ -30,7 +30,7 @@
 author = 'Konstantinos Lampridis'
 
 # The full version, including alpha/beta/rc tags
-release = '1.9.0'
+release = '1.10.0'
 
 # -- General configuration ---------------------------------------------------
 

pyproject.toml

@@ -10,7 +10,7 @@ build-backend = "poetry.core.masonry.api"
 ## Also renders on pypi as 'subtitle'
 [tool.poetry]
 name = "cookiecutter_python"
-version = "1.9.0"
+version = "1.10.0"
 description = "Yet another modern Python Package (pypi) with emphasis in CI/CD and automation."
 authors = ["Konstantinos Lampridis <[email protected]>"]
 maintainers = ["Konstantinos Lampridis <[email protected]>"]

src/cookiecutter_python/__init__.py

@@ -1,3 +1,3 @@
-__version__ = '1.9.0'
+__version__ = '1.10.0'
 
 from . import _logging  # noqa

src/cookiecutter_python/hooks/post_gen_project.py

@@ -59,6 +59,7 @@ def get_request():
             'builder': cookie_dict['docs_builder'],
             'python_runtime': cookie_dict['rtd_python_version'],
         },
+        # internally used to get the template folder of each Doc Builder
         'docs_extra_info': DOCS,
     }
     # sanity check on data dict for docs_website and docs_extra_info
@@ -113,7 +114,10 @@ class PostFileRemovalError(Exception):
 # delete mkdocs.yml if not using mkdocs
 # delete sphinx files if not using sphinx
 builder_id_2_files = {
-    'mkdocs': ['mkdocs.yml'],
+    'mkdocs': [
+        'mkdocs.yml',
+        'scripts/gen_api_refs_pages.py'
+    ],
 }
 
 def post_file_removal(request):

src/cookiecutter_python/{{ cookiecutter.project_slug }}/.github/workflows/policy_docs.yml

@@ -0,0 +1,123 @@
+#################################
+## DOCS STATIC SITE Build/Test ##
+##      Reusable Workflow      ##
+#################################
+
+### TOOLS ###
+# - mkdocs
+# - sphinx
+
+## AUTONOMOUS JOB ##
+
+#  0. Never run
+#  1. Always run
+#  2. Run Docs on conditions
+#     - Triggered on a Long-living branch (ie main)
+#     - Triggered on a v* tag (ie v1.0.0)
+#     - Docs Source Files (ie docs/) changed, compared to previous commit
+#  3. Run Docs, if Source Files changed, compared to previous commit
+
+on:
+  workflow_call:
+    inputs:
+      # Defaults to Policy 2 (CI/CD)
+      run_policy:
+        required: false
+        type: string
+        default: '2'
+      dedicated_branches:
+        required: false
+        type: string
+        default: 'main, master dev'
+      source_code_targets:
+        required: false
+        type: string
+        description: 'Comma separated list of folders to watch for changes'
+        default: 'docs/'
+      ## Parametrizing Runtime Environment (ie py version)
+      python_version:
+        required: false
+        type: string
+        default: '3.10'
+
+jobs:
+  docs_policy:
+    name: "Run Docs Workflow/Job?"
+    runs-on: ubuntu-latest
+    if: always() && inputs.run_policy != 0
+    steps:
+      - if: ${{ "{{" }} !contains('1, 2, 3', inputs.run_policy) {{ "}}" }}
+        run: 'echo "Invalid run_policy: ${{ "{{" }} inputs.run_policy {{ "}}" }}. Must be >0 and <4" && exit 1'
+
+      - if: inputs.run_policy == 1
+        name: 'POLICY: 1 -> Trigger'
+        run: echo "SHOULD_RUN_DOCS=true" >> $GITHUB_ENV
+
+      - if: inputs.run_policy == 2 && contains(inputs.dedicated_branches, github.ref_name)
+        name: 'POLICY: 2 & Branch: ${{ "{{" }} github.ref_name {{ "}}" }} -> Trigger'
+        run: echo "SHOULD_RUN_DOCS=true" >> $GITHUB_ENV
+
+      - if: inputs.run_policy == 2 && startsWith(github.ref, 'refs/tags/v')
+        name: 'POLICY: 2 & Tag: ${{ "{{" }} github.ref_name {{ "}}" }} -> Trigger'
+        run: echo "SHOULD_RUN_DOCS=true" >> $GITHUB_ENV
+
+      - if: ${{ "{{" }} env.SHOULD_RUN_DOCS != 'true' && contains('2, 3', inputs.run_policy) {{ "}}" }}
+        name: 'POLICY: 2, 3 -> Derive from DIFF'
+        run: echo "SHOULD_DERIVE_FROM_DIFF=true" >> $GITHUB_ENV
+
+      - if: ${{ "{{" }} env.SHOULD_DERIVE_FROM_DIFF {{ "}}" }}
+        name: 'POLICY: 2, 3 -> Checkout Code to compute DIFF'
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 2
+
+      - if: ${{ "{{" }} env.SHOULD_DERIVE_FROM_DIFF {{ "}}" }}
+        name: 'POLICY: 2, 3 -> Check Docs Source Files DIFF'
+        run: |
+          echo "============ List Modified Files ============"
+          git diff --name-only HEAD^ HEAD
+          CHANGED_FILES=$(git diff --name-only HEAD^ HEAD)
+
+          # Read Folders we 'Watch' for changes
+          TARGETS=$(echo "${{ "{{" }} inputs.source_code_targets {{ "}}" }}" | tr ',' '\n')
+
+          # Loop through the Watched Folders
+          for TARGET in $TARGETS; do
+            # if rel path of changed file matches glob pattern
+            if [[ $CHANGED_FILES == *"$TARGET"* ]]; then
+              echo "SHOULD_RUN_DOCS=true" >> $GITHUB_ENV
+              echo " --> DOCS Change, from previous commit, found: $TARGET"
+              break
+            fi
+          done
+
+      ### OUTPUT of JOB ###
+      - name: "Set 'Run Docs' Signal to ${{ "{{" }} env.SHOULD_RUN_DOCS {{ "}}" }}"
+        id: set_docs_signal
+        run: echo "RUN_DOCS=${{ "{{" }} env.SHOULD_RUN_DOCS {{ "}}" }}" >> $GITHUB_OUTPUT
+    outputs:
+      RUN_DOCS: ${{ "{{" }} steps.set_docs_signal.outputs.RUN_DOCS {{ "}}" }}
+
+  docs:
+    name: "Docs: Build & Test"
+    runs-on: ubuntu-latest
+    needs: docs_policy
+    if: always() && needs.docs_policy.outputs.RUN_DOCS == 'true'
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python ${{ "{{" }} inputs.python_version {{ "}}" }}
+        uses: actions/setup-python@v4
+        with:
+          python-version: ${{ "{{" }} inputs.python_version {{ "}}" }}
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install tox==3.28
+
+      - name: Install documentation test dependencies
+        if: ${{ "{{" }} matrix.platform == 'macos-latest' && matrix.python-version != '3.6' {{ "}}" }}
+        run: brew install enchant
+
+      - name: Run Documentation Tests
+        if: ${{ "{{" }} matrix.platform == 'ubuntu-latest' || matrix.python-version  != '3.6' {{ "}}" }}
+        run: tox -e docs --sitepackages -vv -s false