Merge pull request #417 from boromir674/dev

Release v2.6.0

Author: boromir674

CHANGELOG.rst

@@ -3,6 +3,43 @@ Changelog
 =========
 
 
+2.6.0 (2025-05-15)
+==================
+
+Changes
+^^^^^^^
+
+feature
+"""""""
+- generate better Mkdocs documentation
+
+test
+""""
+- fix tests
+- fix integration tests
+- simplify code
+
+documentation
+"""""""""""""
+- retire section-index plugin in favor of material built-in !
+- do rebase on Integration Branch to pass GH Rule for Update branch before merge
+- add the 'Topic Branch PR to Dev' Process Guide
+
+refactor
+""""""""
+- apply black
+- pass mypy checks
+- apply ruff
+- apply black
+- apply isort
+- simplify extra_context passing into cookiecutter
+
+chore
+"""""
+- sem ver bump to 2.6.0
+- remove comment from gen_api script
+
+
 2.5.10 (2025-05-10)
 ===================
 

README.md

@@ -3,7 +3,7 @@
 [![Build Status](https://img.shields.io/github/actions/workflow/status/boromir674/cookiecutter-python-package/test.yaml?link=https%3A%2F%2Fgithub.com%2Fboromir674%2Fcookiecutter-python-package%2Factions%2Fworkflows%2Ftest.yaml%3Fquery%3Dbranch%253Amaster)](https://github.com/boromir674/cookiecutter-python-package/actions/workflows/test.yaml?query=branch%3Amaster) [![Coverage](https://img.shields.io/codecov/c/github/boromir674/cookiecutter-python-package/master?logo=codecov)](https://app.codecov.io/gh/boromir674/cookiecutter-python-package) [![Docs](https://img.shields.io/readthedocs/python-package-generator/master?logo=readthedocs&logoColor=lightblue)](https://python-package-generator.readthedocs.io/en/master/) [![Maintainability](https://api.codeclimate.com/v1/badges/1d347d7dfaa134fd944e/maintainability)](https://codeclimate.com/github/boromir674/cookiecutter-python-package/maintainability)
 [![Release Version](https://img.shields.io/pypi/v/cookiecutter_python)](https://pypi.org/project/cookiecutter-python/) [![Wheel](https://img.shields.io/pypi/wheel/cookiecutter-python?color=green&label=wheel)](https://pypi.org/project/cookiecutter-python) [![Tech Debt](https://img.shields.io/codeclimate/tech-debt/boromir674/cookiecutter-python-package)](https://codeclimate.com/github/boromir674/cookiecutter-python-package/) [![Codacy](https://app.codacy.com/project/badge/Grade/5be4a55ff1d34b98b491dc05e030f2d7)](https://app.codacy.com/gh/boromir674/cookiecutter-python-package/dashboard?utm_source=github.com&utm_medium=referral&utm_content=boromir674/cookiecutter-python-package&utm_campaign=Badge_Grade)
 [![Supported Versions](https://img.shields.io/pypi/pyversions/cookiecutter-python?color=blue&label=python&logo=python&logoColor=%23ccccff)](https://pypi.org/project/cookiecutter-python)
-[![PyPI Stats](https://img.shields.io/pypi/dm/cookiecutter-python?logo=pypi&logoColor=%23849ED9&color=%23849ED9)](https://pypistats.org/packages/cookiecutter-python) [![Commits Since Tag](https://img.shields.io/github/commits-since/boromir674/cookiecutter-python-package/v2.5.10/master?color=blue&logo=github)](https://github.com/boromir674/cookiecutter-python-package/compare/v2.5.10..master) [![Commits Since Release](https://img.shields.io/github/commits-since/boromir674/cookiecutter-python-package/latest?color=blue&logo=semver&sort=semver)](https://github.com/boromir674/cookiecutter-python-package/releases)
+[![PyPI Stats](https://img.shields.io/pypi/dm/cookiecutter-python?logo=pypi&logoColor=%23849ED9&color=%23849ED9)](https://pypistats.org/packages/cookiecutter-python) [![Commits Since Tag](https://img.shields.io/github/commits-since/boromir674/cookiecutter-python-package/v2.6.0/master?color=blue&logo=github)](https://github.com/boromir674/cookiecutter-python-package/compare/v2.6.0..master) [![Commits Since Release](https://img.shields.io/github/commits-since/boromir674/cookiecutter-python-package/latest?color=blue&logo=semver&sort=semver)](https://github.com/boromir674/cookiecutter-python-package/releases)
 [![License](https://img.shields.io/github/license/boromir674/cookiecutter-python-package)](https://github.com/boromir674/cookiecutter-python-package/blob/master/LICENSE) [![OpenSSF](https://bestpractices.coreinfrastructure.org/projects/5988/badge)](https://bestpractices.coreinfrastructure.org/en/projects/5988) [![Ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://docs.astral.sh/ruff/) [![Black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
 
 

docs/topics/development/topic_branch_to_dev.md

@@ -0,0 +1,74 @@
+# Board `dev` branch via PR
+
+> Merge `Topic Branch` via **PR** into `Integration Branch`
+
+## `How-to` Open PR to `dev`
+
+Prerequisites:
+
+- Your git HEAD is on the `Topic Branch`
+
+!!! Tip
+    
+    Adjust the instructions, using Inputs for `Default` and `Integration` Branches
+
+    <div class="grid cards" markdown>
+            
+    -   **`INPUT`** Default Branch (ie main)
+    
+        ---
+    
+        <input type="text" id="input-default-branch-name" placeholder="Default Branch name; ie main" oninput="updateReferencesToDefaultBranch()">
+    
+    
+    -   **`INPUT`** Integration Branch (ie dev)
+    
+        ---
+    
+        <input type="text" id="input-integration-branch-name" placeholder="Integration Branch name; ie dev" oninput="updateReferencesToIntegrationBranch()">
+    
+    </div>
+
+<div class="annotate" markdown>
+
+<ol start="1">
+    <li>Define Default and Integration Branches (1)
+
+        <pre><code class="language-sh">
+            <span id="set-default-branch-name">export MAIN_BR=...</span>
+            <span id="set-integration-branch-name">export DEV_BR=...</span>
+        </code></pre>
+    </li>
+
+    <li><b>Open PR</b> to Integration Branch
+
+        ```sh
+        git checkout ${DEV_BR} && git pull && git checkout -
+        git rebase ${DEV_BR} && git push -f && gh pr create --base ${DEV_BR}
+        ```
+
+    </li>
+    <li>Enable <b>Auto Merge</b>
+
+        ```sh
+        gh pr merge --merge --auto
+        ```
+    </li>
+</ol>
+
+<script> function updateReferencesToDefaultBranch() { var inputDefaultBranchName = document.getElementById('input-default-branch-name').value; document.getElementById('set-default-branch-name').innerText = 'export MAIN_BR=' + inputDefaultBranchName; } </script>
+
+<script> function updateReferencesToIntegrationBranch() { var inputIntegrationBranchName = document.getElementById('input-integration-branch-name').value; document.getElementById('set-integration-branch-name').innerText = 'export DEV_BR=' + inputIntegrationBranchName; } </script>
+
+</div>
+
+**Congratulations** :smile: !  
+
+Now the **PR** shall auto-merge once all Required Checks Pass !
+
+## Next Steps
+
+Watch the **PR Validation** `Workflow` "live":
+```sh
+gh run watch
+```

mkdocs.yml

@@ -18,14 +18,20 @@ theme:
     default: material/tag
 
   features:
+    # render a breadcrumb navigation above the title of each page, which might make orientation easier for users visiting your documentation on devices with smaller screens.
     - navigation.path
-    - navigation.top
+    - navigation.top  # back-to-top button shown when user, after scrolling down, starts to scroll up again.
     - navigation.footer
     # enables switching multiple tabs with the same name
     - content.tabs.link
     # renders copy button on code blocks
     - content.code.copy
 
+    - navigation.instant
+    # URL in the address bar is automatically updated with the active anchor as highlighted in the table of contents (right sidebar)
+    - navigation.tracking
+    - navigation.indexes
+
 plugins:
   # Enable jinja inside your markdown files
   # - allows {% include %} statements
@@ -58,7 +64,7 @@ plugins:
   # programmatically generate Nav Item: ie 'reference/' entry in Navigation
   - literate-nav:
       nav_file: SUMMARY.md
-  - section-index
+  # - section-index
 
   # Enable displaying at the bottom of pages the last date of modification!
   # uv add --optional docs 'mkdocs-git-revision-date-localized-plugin'
@@ -169,19 +175,23 @@ nav:
 
       # GitOps / Processes
       - "Reference Processes":
+
         # Process subpage 1
+        - V2:
+          - "Topic Branch into dev": "topics/development/topic_branch_to_dev.md"
+        # Process subpage 2
         - "Release Changes":
           - "topics/development/gitops/index.md"
 
-          - V2:
+          - V1:
             - "Single Branch - Tutorial": "topics/development/gitops/tutorial_release_my_branch_v2.md"
             - "Single Branch - Guide": "topics/development/gitops/gitops-v2.md"
             - "Single Branch - Cheatsheet": "topics/development/gitops/gitops-v2-cheatsheet.md"
             - "Multi Branch - Cheatsheet": "topics/development/gitops/gitops-multi-topics-cheatsheet.md"
 
-        # Process subpage 2
-        - "Docs-only Release": "topics/development/docs_only_release_process.md"
         # Process subpage 3
+        - "Docs-only Release": "topics/development/docs_only_release_process.md"
+        # Process subpage 4
         - "Make an RC (Candidate) Release ": "topics/development/release_candidate.md"
 
   # Tags - Page #

pyproject.toml

@@ -14,7 +14,7 @@ build-backend = "poetry.core.masonry.api"
 name = "cookiecutter_python"
 ### ... ###
 
-version = "2.5.10"
+version = "2.6.0"
 description = "1-click Generator of Python Project, from Template with streamlined \"DevOps\" using a powerful CI/CD Pipeline."
 readme = "README.md"
 license = "AGPL-3.0-only"
@@ -74,7 +74,7 @@ maintainers = [
 license = {text = "AGPL-3.0-only"}
 
 name = "cookiecutter_python"
-version = "2.5.10"
+version = "2.6.0"
 description = "1-click Generator of Python Project, from Template with streamlined \"DevOps\" using a powerful CI/CD Pipeline."
 readme = "README.md"
 # keywords = []
@@ -126,7 +126,6 @@ docs = [
     "mkdocs-macros-plugin>=1.3.7, <2.0.0",
     "mkdocs-material>=9.6.12, <10.0.0",
     "mkdocs-mermaid2-plugin>=1.2.1, <2.0.0",
-    "mkdocs-section-index==0.3.9",
     # mkdocstrings 0.26.1 is the last to support python3.8!
     "mkdocstrings==0.26.1",
     "mkdocstrings-python==1.11.1",

scripts/gen_api_refs_pages.py

@@ -22,7 +22,7 @@
 for path in sorted(
     x for x in src.rglob("*.py") if '{{ cookiecutter.project_slug }}' not in x.parts
 ):
-    print(f"Processing {path}")
+    # print(f"Processing {path}")
     ## 1. extract Relative path from Python File and remove suffix (.py)
     # EG src/biskotaki/cli.py  -->   biskotaki/cli
     _module_path = path.relative_to(src).with_suffix("")

src/cookiecutter_python/__init__.py

@@ -1,3 +1,3 @@
-__version__ = '2.5.10'
+__version__ = '2.6.0'
 
 from . import _logging  # noqa

src/cookiecutter_python/backend/helpers.py

@@ -1,25 +1,28 @@
 import json
 import logging
 import typing as t
+from pathlib import Path
 
+from jinja2 import Environment, FileSystemLoader
+
+from cookiecutter_python.handle.interactive_cli_pipeline import (
+    InteractiveDialogsPipeline,
+)
 
-GivenInterpreters = t.Mapping[str, t.Sequence[str]]
 
 logger = logging.getLogger(__name__)
 
+my_dir = Path(__file__).parent.absolute()
 
-def parse_context(config_file: str):
-    """Render Context on demand, using cookiecutter.json and optional config file."""
-    from pathlib import Path
 
-    my_dir = Path(__file__).parent.absolute()
+GivenInterpreters = t.Mapping[str, t.Sequence[str]]
 
-    # use whatever way cookiecutter uses to render the cookiecutter.json
-    # cookie uses Jinja2
 
-    from jinja2 import Environment, FileSystemLoader
+def parse_context(config_file: str):
+    """Render Context on demand, using cookiecutter.json and optional config file."""
 
-    # render file
+    # use whatever way cookiecutter uses to render the cookiecutter.json
+    # cookiecutter uses Jinja2 to render files
     env = Environment(
         loader=FileSystemLoader(str(my_dir / '..')),
         extensions=['jinja2_time.TimeExtension'],  # shipped with cookiecutter 1.7
@@ -66,10 +69,6 @@ def parse_context(config_file: str):
         **{k: v[0] for k, v in choices.items() if k not in user_default_context},
     )
 
-    from cookiecutter_python.handle.interactive_cli_pipeline import (
-        InteractiveDialogsPipeline,
-    )
-
     pipe = InteractiveDialogsPipeline()
 
     # assert choices['rtd_python_version'] == [], f"DEBUG: {choices['rtd_python_version']}"

src/cookiecutter_python/backend/load_config.py

@@ -10,6 +10,11 @@
 logger = logging.getLogger(__name__)
 
 
+SupportedInterpreters = t.TypedDict(
+    "SupportedInterpreters", {"supported-interpreters": t.Sequence[str]}
+)
+
+
 def load_yaml(config_file) -> t.MutableMapping:
     # TODO use a proxy to load yaml
     with io.open(config_file, encoding='utf-8') as file_handle:
@@ -25,7 +30,7 @@ def load_yaml(config_file) -> t.MutableMapping:
 
 def get_interpreters_from_yaml(
     config_file: str,
-) -> t.Optional[t.Mapping[str, t.Sequence[str]]]:
+) -> t.Optional[SupportedInterpreters]:
     """Parse the 'interpreters' variable out of the user's config yaml file.
 
     Args:
@@ -60,7 +65,7 @@ def _validate_and_get_context(data: t.MutableMapping) -> t.MutableMapping:
 
 def _extract_interpreters(
     context: t.MutableMapping,
-) -> t.Optional[t.Mapping[str, t.Sequence[str]]]:
+) -> t.Optional[SupportedInterpreters]:
     """Extract the interpreters from the 'default_context'."""
     interpreters = context.get('interpreters')
 
@@ -72,14 +77,14 @@ def _extract_interpreters(
         return _parse_interpreters_from_string(interpreters)
 
     if isinstance(interpreters, dict):
-        return interpreters
+        return t.cast(SupportedInterpreters, interpreters)
 
     raise UserYamlDesignError('Interpreters value is not a string or a dictionary')
 
 
 def _parse_interpreters_from_string(
     interpreters: str,
-) -> t.Optional[t.Mapping[str, t.Sequence[str]]]:
+) -> t.Optional[SupportedInterpreters]:
     """Parse interpreters from a JSON string."""
     logger.warning(
         "User's YAML is now expected to contain a dictionary for the 'interpreters' key"

src/cookiecutter_python/backend/main.py

@@ -39,11 +39,7 @@ def generate(
     'artifacts', and Continuous Documentation of the Python Project.
     """
     print('Start Python Generator !')
-    # Initialize Generation Request:
-    #  - store the CI Test Matrix Python Interpreters versions list
-    #       -  prompt for user input in interactive or atempt to read from yaml otherwise
-    #  - prepare Cookiecutter extra context:
-    #      - add interpreters versions list
+    # Future HTTP requests to pypi.org and readthedocs.org web servers
     request = pre_main(
         Request(
             config_file=config_file,
@@ -54,9 +50,9 @@ def generate(
             offline=offline,
         )
     )
-    print('Extra context: ', request.extra_context)
     ## GENERATION from Template; delegate to Cookiecutter callable ##
     project_dir = generator(
+        # COOKIECUTTER TEMPLATE (cookiecutter.json)
         os.path.abspath(os.path.join(my_dir, '..')),  # template dir path
         checkout=checkout,
         # no_input=no_input,