[NEW] Better Mkdocs Infra

Release Version '1.14.0' into 'master' Branch

Author: boromir674

.github/biskotaki.yaml

@@ -11,9 +11,9 @@ default_context:
     email: k.lampridis@hotmail.com
     author_email: k.lampridis@hotmail.com
     github_username: boromir674
-    project_short_description: Project generated from the https://github.com/boromir674/cookiecutter-python-package/tree/master/src/cookiecutter_python cookiecutter
+    project_short_description: Project generated using https://github.com/boromir674/cookiecutter-python-package
     initialize_git_repo: no
-    interpreters: {"supported-interpreters": ["3.6", "3.7", "3.8", "3.9", "3.10"]}
+    interpreters: {"supported-interpreters": ["3.7", "3.8", "3.9", "3.10", "3.11"]}
     ## Documentation Config ##
     docs_builder: "sphinx"
     ## READ THE DOCS CI Config ##

.github/workflows/generate.yaml

@@ -8,6 +8,8 @@ on:
     branches:
       - 'master'
 
+env:
+  PY_VERSION: '3.11'
 
 jobs:
   generate:
@@ -17,10 +19,10 @@ jobs:
       SUPER_SECRET: ${{ secrets.BISKOTAKI_GH_TOKEN }}
     steps:
       - uses: actions/checkout@v4
-      - name: Set up Python 3.10
+      - name: Set up Python ${{ env.PY_VERSION }}
         uses: actions/setup-python@v5
         with:
-          python-version: "3.10"
+          python-version: "${{ env.PY_VERSION }}"
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
@@ -50,7 +52,7 @@ jobs:
         run: |
           pip install --user -e .
           echo "    version: \"${{ env.PKG_VERSION }}\"" >> .github/biskotaki.yaml
-          generate-python -o gen --config-file ./.github/biskotaki.yaml --no-input -f
+          generate-python -o gen --config-file ./.github/biskotaki.yaml --no-input -f --offline
 
       ## VALIDATE BISKOTAKI CI CONFIG file is in valid Yaml format ##
       - name: "Validate YAML format"
@@ -63,30 +65,44 @@ jobs:
 
       ## Run Test Suite against the generated project ##
       - name: Test distributions 'Source', 'Built' and 'edit' (dev env) mode installation
+        env:
+          TOXPYTHON: "python${{ env.PY_VERSION }}"
         run: |
           cd gen/biskotaki
-          tox -e "py310{-sdist, -wheel, -dev}"
+          tox -e 'edit,sdist,wheel'
+          tox -e wheel-test
           tox -e coverage
+      
+      ## Verify all Tox Envs PASS, as intented, out of the box ##
+
+      # Running Type Check, on src and Test code: Passes
+      - name: 'Mypy: Static Type Checker -> PASS'
+        run: |
+          cd gen/biskotaki
+          tox -e pin-deps -- -E typing
+          tox -e type
 
-      ## Verify Development Scripts operate as intented out of the box
       - name: 'Ruff: Fast Python Linter -> PASS'
         run: |
           cd gen/biskotaki
           tox -e ruff
-
       # Running Lint Check, on src and Test code: Passes
-      # Running Type Check, on src and Test code: Passes
-      # Running the Build script (sdist and wheel): produces Distro Artifacts: Source (.tar.gz) and Wheel (.whl) files
-      # Running Quality Checks against Distro Metadata: Passes with 10/10 score
-
-      - name: Run Isort, Black, Mypy, Build, Pyroma and PyDeps commands
+      - name: 'Isort, Black: Code Formatter -> PASS'
         run: |
           cd gen/biskotaki
           tox -e lint
-          tox -e type
+      # Running the Build script (sdist and wheel): produces Distro Artifacts: Source (.tar.gz) and Wheel (.whl) files
+      - name: 'Build: sdist, wheel -> PASS'
+        run: |
+          cd gen/biskotaki
           tox -e build
+      # Running Quality Checks against Distro Metadata: Passes with 10/10 score
+      - name: 'Pyroma: Distro Quality -> PASS'
+        run: |
+          cd gen/biskotaki
           tox -e check
-          # tox -e graphs
+
+      # tox -e graphs
 
       ## PUSH to BISKOTAKI REPO ##
       - name: Push to dedicated branch in biskotaki repo

CHANGELOG.rst

@@ -2,6 +2,35 @@
 Changelog
 =========
 
+1.14.0 (2024-02-18)
+===================
+
+Changes
+^^^^^^^
+
+feature
+"""""""
+- revamp Mkdocs build Process, and enhance Template Content of Docs Pages
+
+fix
+"""
+- provide correct env name for Code Visualization CI Job to reference
+- fix biskotaki generation with sphinx docs
+
+test
+""""
+- update tests to match new expectations, given biskotaki.yml updates
+- update Gold Standard Biskotatki Snapshot
+
+ci
+""
+- update Generate Workflow, according to changed tox
+
+chore
+"""""
+- remove python 3.6 and add python 3.11 from Biskotaki Ref Project
+
+
 1.13.0 (2024-02-15)
 ===================
 

README.rst

@@ -275,9 +275,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.13.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.14.0/master?color=blue&logo=github
     :alt: GitHub commits since tagged version (branch)
-    :target: https://github.com/boromir674/cookiecutter-python-package/compare/v1.13.0..master
+    :target: https://github.com/boromir674/cookiecutter-python-package/compare/v1.14.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.13.0'
+release = '1.14.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.13.0"
+version = "1.14.0"
 description = "1-click Generator of Python Project, from Template with streamlined \"DevOps\" using a powerful CI/CD Pipeline."
 authors = ["Konstantinos Lampridis <k.lampridis@hotmail.com>"]
 maintainers = ["Konstantinos Lampridis <k.lampridis@hotmail.com>"]

src/cookiecutter_python/__init__.py

@@ -1,3 +1,3 @@
-__version__ = '1.13.0'
+__version__ = '1.14.0'
 
 from . import _logging  # noqa

src/cookiecutter_python/{{ cookiecutter.project_slug }}/.github/workflows/test.yaml

@@ -132,62 +132,81 @@ jobs:
     if: ${{ "{{" }} needs.set_github_outputs.outputs.TESTS_ENABLED == 'true' {{ "}}" }}
     strategy:
       matrix: ${{ "{{" }}fromJSON(needs.set_github_outputs.outputs.matrix){{ "}}" }}
+    env:
+      WHEELS_PIP_DIR: "wheels-pip"
     steps:
       - run: echo "Platform -> ${{ "{{" }} matrix.platform {{ "}}" }} , Python -> ${{ "{{" }} matrix.python-version {{ "}}" }}"
-      - uses: actions/checkout@v3
       - name: Set up Python ${{ "{{" }} matrix.python-version {{ "}}" }}
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: ${{ "{{" }} matrix.python-version {{ "}}" }}
       - run: python -m pip install --upgrade pip && python -m pip install tox==3.28 tox-gh-actions
 
+      - uses: actions/checkout@v4
+
+      - name: Pin 'Static Type Checking' Dependencies
+        run: tox -vv -s false -e pin-deps -- -E typing
+
       - name: Do Type Checking
         run: tox -e type -vv -s false
 
-      # Steps 'Run Unit Tests' and 'Check for compliance with Python Best Practices'
-      # require the PKG_VERSION environment variable at runtime
-
-      # We want to read the Version value from a file, that is part of the
-      # Python Distro (.tar.gz, or wheel)
-      - name: 'Define executable Parser, to read from same Source of Truth that Generator CLI utilizes, at runtime'
-        run: echo PARSER="./scripts/parse_version.py" >> $GITHUB_ENV
-
-      # Note: one Sem Ver is maintained in src/**/__init__.py file
-      # and the other in the pyproject.toml file
-      - name: 'Parse Sem Ver, same as `generate-python --version` value returned, at runtime'
-        run: echo VERSION_FROM_DISTRO_SOURCE_PY_FILE="$(${{ "{{" }} env.PARSER {{ "}}" }})" >> $GITHUB_ENV
-
-      # PEP 440 requires that the version string be normalized to a canonical form.
-      # below should be enough to handle cases: '1.7.4', '1.7.4-rc', and '1.7.4-rc.1'
-      - name: 'Transform Version (ie 1.7.4-rc.1 -> 1.7.4rc1), to match the name of the wheel produced'
-        run: echo WHEEL_VERSION="$(echo $VERSION_FROM_DISTRO_SOURCE_PY_FILE | sed -E 's/([^.]*)\.([^.]*)\.([^-]*)-(rc)\.?(.*)/\1.\2.\3\4\5/')" >> $GITHUB_ENV
-
-      - name: "If Sem Ver ends with '-rc', append trailing 0 (ie *rc0)"
-        id: extract_sem_ver_last_two_chars
-        run: 'echo last_two="${${{ "{{" }} env.WHEEL_VERSION {{ "}}" }}: -2}" >> $GITHUB_OUTPUT'
-
-      - name: "Sem Ver ends with 'rc' = ${{ "{{" }} steps.extract_sem_ver_last_two_chars.outputs.last_two == 'rc' {{ "}}" }}"
-        if: ${{ "{{" }} steps.extract_sem_ver_last_two_chars.outputs.last_two == 'rc' {{ "}}" }}
-        run: echo WHEEL_VERSION="${WHEEL_VERSION}0" >> $GITHUB_ENV
-
-      - name: 'Set Expected PEP 440 Version: ${{ "{{" }} env.WHEEL_VERSION {{ "}}" }}'
-        id: set_expected_pep_440_version
-        run: echo "EXPECTED_PEP_440_VERSION=${{ "{{" }} env.WHEEL_VERSION {{ "}}" }}" >> $GITHUB_OUTPUT
-      
-      ##### TEST SUITE / UNIT TESTS #####
-        # Before Test Suite, must derive expected PEP 440 Sem Ver
-      - name: Run Unit Tests
-        run: tox -vv -s false
+      ###### TEST SUITE RUN against Edit and Sdist ######
+      - name: Build and Test 'Edit' and 'Sdist' & Build Wheel(s)
+        run: |
+          set -o pipefail
+          tox -vv -s false | tee test_output.log
         env:
           PLATFORM: ${{ "{{" }} matrix.platform {{ "}}" }}
-          PKG_VERSION: ${{ "{{" }} steps.set_expected_pep_440_version.outputs.EXPECTED_PEP_440_VERSION {{ "}}" }}
+          BUILD_DEST: ${{ "{{" }} env.WHEELS_PIP_DIR {{ "}}" }}
+
+      - name: List Wheel(s) created for Distro and its Requirements
+        run: ls -l ${{ "{{" }} env.WHEELS_PIP_DIR {{ "}}" }}
+
+      ### PARSE WHEEL File NAME ###
+      - name: Extract Wheel Name and Size
+        id: extract_wheel_info
+        shell: bash
+        run: |
+          WHEEL_INFO=$(grep -E "Created wheel for" test_output.log | sed -E "s/.*filename=([^ ]+) size=([^ ]+) .*/\1 \2/")
+
+          # extract file name
+          WHEEL_NAME=$(echo $WHEEL_INFO | cut -d ' ' -f 1)
+          echo "WHEEL_NAME=$WHEEL_NAME" >> $GITHUB_ENV
+
+          # extract file size
+          WHEEL_SIZE=$(echo $WHEEL_INFO | cut -d ' ' -f 2)
+          echo "WHEEL_SIZE=$WHEEL_SIZE" >> $GITHUB_ENV
 
+          # extract '1.12.5.dev0' from '{{ cookiecutter.pkg_name }}-1.12.5.dev0-py3-none-any.whl'
+          PEP_VERSION=$(echo $WHEEL_NAME | sed -E "s/{{ cookiecutter.pkg_name }}-([^ ]+)-py3-none-any.whl/\1/")
+
+          echo "PEP_VERSION=${PEP_VERSION}" >> $GITHUB_OUTPUT
+
+      - run: 'echo "WHEEL_NAME: $WHEEL_NAME SIZE: $WHEEL_SIZE"'
+      - run: 'echo "PEP_VERSION: $PEP_VERSION"'
+
+      # Crash Workflow if PEP_VERSION is not set
+      - if: ${{ "{{" }} steps.extract_wheel_info.outputs.PEP_VERSION == '' {{ "}}" }}
+        run: exit 1
+
+      ###### TEST SUITE RUN against Wheel ######
+      - name: Run Test Suite Against Wheel
+        run: tox -e wheel-test -s false
+        env:
+          PLATFORM: ${{ "{{" }} matrix.platform {{ "}}" }}
+          BUILD_DEST: ${{ "{{" }} env.WHEELS_PIP_DIR {{ "}}" }}
+          WHEEL: ${{ "{{" }} env.WHEEL_NAME {{ "}}" }}
+
+      ## Combine Coverage Data from Tests' Results ##
       - name: "Combine Coverage (dev, sdist, wheel) & make Reports"
         run: tox -e coverage --sitepackages -vv -s false
 
       - name: Rename Coverage Files
-        run: mv ./.tox/coverage.xml ./coverage-${{ "{{" }} matrix.platform {{ "}}" }}-${{ "{{" }} matrix.python-version {{ "}}" }}.xml
+        shell: bash
+        run: |
+          mv ./.tox/coverage.xml ./coverage-${{ "{{" }} matrix.platform {{ "}}" }}-${{ "{{" }} matrix.python-version {{ "}}" }}.xml
 
+      ## UPLOAD CI ARTIFACTS - Coverage Reports ##
       - name: "Upload Test Coverage as Artifacts"
         uses: actions/upload-artifact@v3
         with:
@@ -196,25 +215,27 @@ jobs:
           if-no-files-found: error
 
       - name: Check for compliance with Python Best Practices
+        shell: bash
         env:
-          PKG_VERSION: ${{ "{{" }} steps.set_expected_pep_440_version.outputs.EXPECTED_PEP_440_VERSION {{ "}}" }}
+          PKG_VERSION: ${{ "{{" }} steps.extract_wheel_info.outputs.PEP_VERSION {{ "}}" }}
+          WHEEL_PATH: ${{ "{{" }} env.WHEELS_PIP_DIR {{ "}}" }}/${{ "{{" }} env.WHEEL_NAME {{ "}}" }}
         run: |
           DIST_DIR=dist
-          echo "DIST_DIR=dist" >> $GITHUB_ENV
+          echo "DIST_DIR=${DIST_DIR}" >> $GITHUB_ENV
           mkdir ${DIST_DIR}
           mv ".tox/${DIST_DIR}/{{ cookiecutter.pkg_name }}-${PKG_VERSION}.tar.gz" "${DIST_DIR}"
-          mv ".tox/${DIST_DIR}/{{ cookiecutter.pkg_name }}-${PKG_VERSION}-py3-none-any.whl" "${DIST_DIR}"
+          mv "${{ "{{" }} env.WHEEL_PATH {{ "}}" }}" "${DIST_DIR}"
           tox -e check -vv -s false
 
+      ## UPLOAD CI ARTIFACTS - Distro Build(s), 1 sdist and 1 or more wheels ##
       - name: Upload Source & Wheel distributions as Artefacts
         uses: actions/upload-artifact@v3
         with:
           name: dist-${{ "{{" }} matrix.platform {{ "}}" }}-${{ "{{" }} matrix.python-version {{ "}}" }}
           path: ${{ "{{" }} env.DIST_DIR {{ "}}" }}
           if-no-files-found: error
     outputs:
-      EXPECTED_PEP_440_VERSION: ${{ "{{" }} steps.set_expected_pep_440_version.outputs.EXPECTED_PEP_440_VERSION {{ "}}" }}
-
+      PEP_VERSION: ${{ "{{" }} steps.extract_wheel_info.outputs.PEP_VERSION {{ "}}" }}
 
   codecov_coverage_host:
     runs-on: ubuntu-latest
@@ -302,7 +323,7 @@ jobs:
       name: ${{ "{{" }} needs.check_which_git_branch_we_are_on.outputs.ENVIRONMENT_NAME {{ "}}" }}
     env:
       DIST_DIR: dist
-      PACKAGE_DIST_VERSION: ${{ "{{" }} needs.test_suite.outputs.EXPECTED_PEP_440_VERSION {{ "}}" }}
+      PACKAGE_DIST_VERSION: ${{ "{{" }} needs.test_suite.outputs.PEP_VERSION {{ "}}" }}
       TWINE_USERNAME: ${{ "{{" }} secrets.TWINE_USERNAME {{ "}}" }}
       TWINE_PASSWORD: ${{ "{{" }} secrets.TWINE_PASSWORD {{ "}}" }}
       PYPI_SERVER: ${{ "{{" }} vars.PYPI_SERVER {{ "}}" }}
@@ -369,10 +390,11 @@ jobs:
   docs:
     name: Build Documentation
     needs: set_github_outputs
-    uses: ./.github/workflows/policy_docs.yml
+    uses: boromir674/automated-workflows/.github/workflows/policy_docs.yml@v1.3.0
     with:
       run_policy: ${{ "{{" }} needs.set_github_outputs.outputs.PIPE_DOCS_POLICY {{ "}}" }}
       python_version: ${{ "{{" }} needs.set_github_outputs.outputs.PIPE_DOCS_PY {{ "}}" }}
+      command: 'tox -s false -e pin-deps -- -E docs && tox -e docs --sitepackages -vv -s false'
 
 ### DRAW PYTHON DEPENDENCY GRAPHS ###
   code_visualization:

src/cookiecutter_python/{{ cookiecutter.project_slug }}/.readthedocs.yml

@@ -19,6 +19,7 @@ build:
       - python -m poetry export -o req-docs.txt -E docs
     post_install:
       - python -m pip install -e .
+      - python -m pip install pyyaml
     pre_build:
       - python ./scripts/visualize-ga-workflow.py > ./docs/cicd_mermaid.md
       - python ./scripts/visualize-dockerfile.py > ./docs/dockerfile_mermaid.md