python-template-project 0.1.15__tar.gz → 0.1.19__tar.gz

python_template_project-0.1.19/.github/rename_project.sh

@@ -0,0 +1,78 @@
+#!/usr/bin/env bash
+
+# Hilfsfunktion für Fehlermeldungen und Beenden
+function die { echo "$*" >&2; exit 1; }
+
+# parse args
+while getopts a:p:n:d: flag
+do
+    case "${flag}" in
+        a) author=${OPTARG};;
+        p) package_name=${OPTARG};; # The new internal Python package name (snake_case)
+        n) project_name=${OPTARG};; # The new external project name (kebab-case)
+        d) description=${OPTARG};;
+        *) die "Unknown Flag: $flag";;
+    esac
+done
+
+# Check whether all required arguments have been passed
+[[ -z "$author" ]] && die "Missing Argument: -a (author)"
+[[ -z "$package_name" ]] && die "Missing Argument: -p (package_name)"
+[[ -z "$project_name" ]] && die "Missing Argument: -n (project_name)"
+[[ -z "$description" ]] && die "Missing Argument: -d (description)"
+
+echo "Author: $author";
+echo "New Python Package Name (internal): $package_name";
+echo "New Project Name (external/PyPI): $project_name";
+echo "Description: $description";
+
+echo "Renaming project content..."
+
+# Old identifiers
+original_author="pamagister"
+original_project_name="python-template-project"
+original_package_name="python_template_project"
+original_description="Feature-rich Python project template designed for robustness and ease of use."
+
+# Customize all file contents first
+# Use 'git ls-files' to edit only versioned files
+# Note the order: Replace more specific with more specific first,
+# then more general ones.
+# Important: Escape special characters in the variables if they could occur in the replacements.
+# Here the variables are relatively safe as they only contain alphanumeric characters and hyphens/underscores.
+
+for filename in $(git ls-files)
+do
+    # Skip files in the .github/ directory
+    if [[ "$filename" == ".github"* ]]; then
+        echo "Skipping .github file: $filename"
+        continue
+    fi
+    # Replace the old internal package name with the new internal package name
+    sed -i "s/$original_package_name/$package_name/g" "$filename"
+    # Replace the old external project name with the new external project name
+    sed -i "s/$original_project_name/$project_name/g" "$filename"
+    # Replace the old author
+    sed -i "s/$original_author/$author/g" "$filename"
+    # Replace the old description with the new one
+    sed -i "s/$original_description/$description/g" "$filename"
+    echo "Processed: $filename"
+done
+
+# Then rename the directory
+# Check if the directory exists before renaming it
+OLD_PACKAGE_DIR="src/$original_package_name"
+NEW_PACKAGE_DIR="src/$package_name"
+
+if [ -d "$OLD_PACKAGE_DIR" ]; then
+    echo "Renaming directory: $OLD_PACKAGE_DIR to $NEW_PACKAGE_DIR"
+    mv "$OLD_PACKAGE_DIR" "$NEW_PACKAGE_DIR"
+else
+    echo "Warning: Directory $OLD_PACKAGE_DIR not found. Skipping directory rename."
+fi
+
+# Remove the template.yml to indicate that the template has been applied
+echo "Removing .github/template.yml"
+rm -f .github/template.yml
+
+echo "Project renaming complete!"

python_template_project-0.1.19/.github/template.yml

@@ -0,0 +1,2 @@
+author: pamagister
+# Thanks and credits to rochacbruno, but i wanted to extend the functionality

python_template_project-0.1.19/.github/workflows/build-macos.yml

@@ -0,0 +1,42 @@
+name: Build macOS App
+
+on:
+  push:
+    tags:
+      - '*'  # Triggers for tags like 0.1 or v0.1.3
+  workflow_dispatch:  # Allows manual triggering
+
+jobs:
+  build:
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: [ 3.11 ]
+        os: [ macos-latest ]
+    runs-on: ${{ matrix.os }}
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Setup Environment # Composite Action
+        uses: ./.github/actions/setup-environment
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Build Unified Executable and App Bundle with PyInstaller
+        run: |
+          run: make build-win
+
+      - name: Upload ZIP to GitHub Release
+        uses: softprops/action-gh-release@v2
+        if: startsWith(github.ref, 'refs/tags/')
+        with:
+          files: package-macOS.zip
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

{python_template_project-0.1.15 → python_template_project-0.1.19}/.github/workflows/build.yml

@@ -29,16 +29,10 @@ jobs:
           python-version: ${{ matrix.python-version }}
 
       - name: Build Unified EXE with PyInstaller
-        run: |
-          echo "Building unified CLI/GUI application"
-          uv run pyinstaller --onefile src/main.py --name python-template-project --add-data "config.yaml;." --hidden-import python_template_project.cli.cli --hidden-import python_template_project.gui.gui
+        run: make build-win
 
       - name: Prepare ZIP file for release
         run: |
-          mkdir release
-          copy dist\python-template-project.exe release\
-          copy config.yaml release\
-          copy README.md release\
           echo "  - Double-click to start GUI" >> release\USAGE.txt
           echo "  - Run from command line for CLI options" >> release\USAGE.txt
           powershell Compress-Archive -Path release\* -DestinationPath installer-win.zip

python_template_project-0.1.19/.github/workflows/rename_project.yml

@@ -0,0 +1,62 @@
+name: Rename the project from template
+
+on: [push]
+
+permissions: write-all
+
+jobs:
+  rename-project:
+    if: ${{ !contains (github.repository, 'python-template-project') }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          # by default, it uses a depth of 1
+          # this fetches all history so that we can read each commit
+          fetch-depth: 0
+          ref: ${{ github.head_ref }}
+          
+      # The repository name (e.g. "my-new-repo" or "my_new_repo")
+      - run: echo "NEW_REPO_BASE_NAME=$(echo '${{ github.repository }}' | awk -F '/' '{print $2}')" >> $GITHUB_ENV
+        shell: bash
+
+      # The name for internal Python packages (always with underscores)
+      - run: echo "NEW_PACKAGE_NAME=$(echo '${{ env.NEW_REPO_BASE_NAME }}' | tr '-' '_')" >> $GITHUB_ENV
+        shell: bash
+
+      # The name for external designations (remains as in the repo name)
+      - run: echo "NEW_PROJECT_NAME=$(echo '${{ env.NEW_REPO_BASE_NAME }}' | tr '_' '-')" >> $GITHUB_ENV
+        shell: bash
+
+      - run: echo "REPOSITORY_OWNER=$(echo '${{ github.repository }}' | awk -F '/' '{print $1}')" >> $GITHUB_ENV
+        shell: bash
+        
+      - name: Check if this is still a template
+        id: is_template
+        # Check whether the template.yml still exists
+        run: echo "::set-output name=is_template::$(test -f .github/template.yml && echo 'true' || echo 'false')"
+
+      - name: Rename the project
+        # Execute only if the template.yml exists (indicator for template repo)
+        if: steps.is_template.outputs.is_template == 'true'
+        run: |
+          echo "Renaming the project with author: ${{ env.REPOSITORY_OWNER }}, package name: ${{ env.NEW_PACKAGE_NAME }}, project name: ${{ env.NEW_PROJECT_NAME }}"
+          .github/rename_project.sh \
+            -a "${{ env.REPOSITORY_OWNER }}" \
+            -p "${{ env.NEW_PACKAGE_NAME }}" \
+            -n "${{ env.NEW_PROJECT_NAME }}" \
+            -d "Feature-rich Python project template for ${{ env.NEW_PROJECT_NAME }}." # Customized description
+
+      - name: Configure Git # it is good practiceto configure git bot
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          # 'git config --global credential.helper store'
+        shell: bash
+
+      - name: Commit and Push Changes
+        run: |
+          git add .
+          git commit -m "✅ Project renamed from template."
+          git push --force
+        shell: bash

{python_template_project-0.1.15 → python_template_project-0.1.19}/HISTORY.md

@@ -4,6 +4,41 @@ Changelog
 
 (unreleased)
 ------------
+- Feat #30: do not track _version.py. [Paul Magister]
+- Feat #30: fix version. [Paul Magister]
+
+
+0.1.17 (2025-06-20)
+-------------------
+- Feat #30: fix link issue by modifying link in README.md. [Paul
+  Magister]
+
+
+0.1.16 (2025-06-20)
+-------------------
+- Fix #29: more rubust usage of srtm in case of connection issues. [Paul
+  Magister]
+- Feat #30: exclude _version.py from check. [Paul Magister]
+- Feat #31: doc on how to generate. [Paul Magister]
+- Feat #30: exclude _version.py from check. [Paul Magister]
+- Feat #31: enable project to be copied #31. [Paul Magister]
+- Feat #27: move build logic into make file #27. [Paul Magister]
+- Feat #30: improve README.md, fix utf8-issues on copying. [Paul
+  Magister]
+- Feat #30: correct doc how to install and use this project. [Paul
+  Magister]
+- Feat #30: add _version.py instead of VERSION. [Paul Magister]
+- Update README.md from docs/index.md. [github-actions]
+
+
+0.1.15 (2025-06-20)
+-------------------
+- Feat #30: switch build system to setuptools_scm. [Paul Magister]
+- Feat #30: add some links to the doc. [Paul Magister]
+
+
+0.1.14 (2025-06-20)
+-------------------
 - Feat #30: release project on pypi: deploy section in release.yml.
   [Paul Magister]
 - Feat #30: release project on pypi: rename contributing section, add

{python_template_project-0.1.15 → python_template_project-0.1.19}/Makefile

@@ -55,6 +55,42 @@ test: lint        ## Run tests and generate coverage report.
 	uv run coverage xml
 	uv run coverage html
 
+.PHONY: build-win
+build-win:    ## Build the Windows executable.
+	echo "Building unified CLI/GUI application"
+	uv run pyinstaller --onefile src/main.py --name python-template-project --add-data "config.yaml;." --hidden-import python_template_project.cli.cli --hidden-import python_template_project.gui.gui
+	rm -rf release
+	mkdir release
+	cp dist/python-template-project.exe release
+	cp config.yaml release
+	cp README.md release
+
+.PHONY: build-macos
+build-macos:    ## Build the macOS executable.
+	echo "Building unified CLI/GUI application as executable"
+	uv run pyinstaller --onefile src/main.py --name python-template-project --add-data "config.yaml:." --hidden-import python_template_project.cli.cli --hidden-import python_template_project.gui.gui
+
+	echo "Building unified CLI/GUI application as .app bundle"
+	# --windowed is important to hide the console for GUI mode
+	# The name "TemplateApp" becomes the name of the .app
+	uv run pyinstaller --windowed --name "TemplateApp" src/main.py --add-data "config.yaml:." --hidden-import python_template_project.cli.cli --hidden-import python_template_project.gui.gui
+
+	# Prepare ZIP file for release
+	rm -rf release
+	mkdir release
+	echo "Copy the CLI/GUI executable"
+	cp dist/python-template-project release/
+	echo "Copy the .app bundle (directory) recursively"
+	cp -R "dist/TemplateApp.app" release/
+	echo "Copy configuration and documentation"
+	cp config.yaml release/
+	cp README.md release/
+	echo "Create usage instructions"
+
+	echo "Create the ZIP archive from the contents of the release folder"
+	cd release
+	zip -r ../package-macOS.zip .
+
 .PHONY: watch
 watch:            ## Run tests on every change.
 	ls **/**.py | entr uv run pytest -s -vvv -l --tb=long --maxfail=1 tests/

{python_template_project-0.1.15 → python_template_project-0.1.19}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-template-project
-Version: 0.1.15
+Version: 0.1.19
 Summary: Feature-rich Python project template designed for robustness and ease of use.
 Author: pamagister
 Requires-Python: <3.12,>=3.10
@@ -43,54 +43,44 @@ A feature-rich Python project template with with auto-generated CLI, GUI and par
 
 This template provides a solid foundation for your next Python project, incorporating best practices for testing, automation, and distribution. It streamlines the development process with a comprehensive set of pre-configured tools and workflows, allowing you to focus on writing code.
 
+## Installation
 
-## Feature overview
+Download from [PyPI](https://pypi.org/).
 
-* **Testing:** Unit testing setup with `pytest`.
-* **CI/CD:**  [GitHub Actions](https://github.com/features/actions) for automated builds (Windows, macOS), unit tests, and code checks.
-* **Code Formatting and Linting:** Pre-commit hook with the [RUFF auto-formatter](https://docs.astral.sh/ruff/) to ensure consistent code style.
-* **Automated Builds:** GitHub pipeline for automatically building a Windows executable and a macOS installer.
-* **Package Management:** Utilizes [uv](https://docs.astral.sh/uv/getting-started/), an extremely fast Python package manager, with dependencies managed in `pyproject.toml`.
-* **Parameter-Driven Automation:**
-    * Automatic generation of a configuration file from parameter definitions.
-    * Automatic generation of a Command-Line Interface (CLI) from the same parameters.
-    * Automatic generation of CLI API documentation.
-* **Documentation:** Configuration for publishing documentation on [Read the Docs](https://about.readthedocs.com/) using [mkdocs](https://www.mkdocs.org/) .
-* **Workflow Automation:** A `Makefile` is included to simplify and automate common development tasks.
-* **Minimalist GUI:** Comes with a basic GUI based on [tkinker](https://tkdocs.com/tutorial/index.html) that includes an auto-generated settings menu based on your defined parameters.
-* **Release pipeline:** Automated releases unsing the Makefile `make release` command, which creates a new tag and pushes it to the remote repo. The `release` pipeline will automatically create a new release on GitHub and trigger a release on PyPI.
-    * **[setuptools](https://pypi.org/project/setuptools/)** is used to package the project and manage dependencies.
-    * **[setuptools-scm](https://pypi.org/project/setuptools-scm/)** is used to automatically generate the `_version.py` file from the `pyproject.toml` file.
+💾 For more installation options see [install](getting-started/install.md).
 
-## Getting started
-
-1. **Create** a new [github repository](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-new-repository).
-2. **Clone** [github repository](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository) the into your local file system.
-    ```bash
-    git clone https://github.com/YOUR-USERNAME/YOUR-REPOSITORY
-    ```
-4. **Install** [uv package and project manager](https://docs.astral.sh/uv/getting-started/installation/)
-    ```bash
-    pip install uv
-    ```
-5. **Generate** [a sample project](https://docs.astral.sh/uv/guides/projects/#creating-a-new-project) with uv
-6. Add and **push** the artifacts to your github repository
-    ```bash
-    git push
-    ```
-8. Copy the content of this repository into your repository
-
-## Troubleshooting
-
-### Problems with release pipeline
-
-If you get this error below:
 ```bash
-/home/runner/work/_temp/xxxx_xxx.sh: line 1: .github/release_message.sh: Permission denied
+pip install python-template-project
 ```
 
-You have to run these commands in your IDE Terminal or the git bash and then push the changes.
+Run GUI from command line
+
 ```bash
-git update-index --chmod=+x ./.github/release_message.sh
+python-template-project-gui
 ```
 
+## How to use this template
+
+🐍 For details, see the [Getting Started](develop/01_getting_started_dev.md) guide.
+
+
+## Feature overview
+
+* 📦 **Package Management:** Utilizes [uv](https://docs.astral.sh/uv/getting-started/), an extremely fast Python package manager, with dependencies managed in `pyproject.toml`.
+* ✅ **Code Formatting and Linting:** Pre-commit hook with the [RUFF auto-formatter](https://docs.astral.sh/ruff/) to ensure consistent code style.
+* 🧪 **Testing:** Unit testing framework with [pytest](https://docs.pytest.org/en/latest/).
+* 📊 **Code coverage reports** using [codecov](https://about.codecov.io/sign-up/)
+* 🔄 **CI/CD:**  [GitHub Actions](https://github.com/features/actions) for automated builds (Windows, macOS), unit tests, and code checks.
+* 💾 **Automated Builds:** GitHub pipeline for automatically building a Windows executable and a macOS installer.
+* 💬 **Parameter-Driven Automation:**
+    * Automatic generation of a configuration file from parameter definitions.
+    * Automatic generation of a Command-Line Interface (CLI) from the same parameters.
+    * Automatic generation of CLI API documentation.
+    * Automatic generation of change log using **gitchangelog** to keep a HISTORY.md file up to date.
+* 📃 **Documentation:** Configuration for publishing documentation on [Read the Docs](https://about.readthedocs.com/) using [mkdocs](https://www.mkdocs.org/) .
+* 🖼️ **Minimalist GUI:** Comes with a basic GUI based on [tkinker](https://tkdocs.com/tutorial/index.html) that includes an auto-generated settings menu based on your defined parameters.
+* 🖥️ **Workflow Automation:** A `Makefile` is included to simplify and automate common development tasks.
+* 🛳️ **Release pipeline:** Automated releases unsing the Makefile `make release` command, which creates a new tag and pushes it to the remote repo. The `release` pipeline will automatically create a new release on GitHub and trigger a release on  [PyPI](https://pypi.org.
+    * **[setuptools](https://pypi.org/project/setuptools/)** is used to package the project and manage dependencies.
+    * **[setuptools-scm](https://pypi.org/project/setuptools-scm/)** is used to automatically generate the `_version.py` file from the `pyproject.toml` file.
+

python_template_project-0.1.19/README.md

@@ -0,0 +1,57 @@
+<!-- This README.md is auto-generated from docs/index.md -->
+
+# Welcome to python-template-project
+
+A feature-rich Python project template with with auto-generated CLI, GUI and parameterized configuration.
+
+[![Github CI Status](https://github.com/pamagister/python-template-project/actions/workflows/main.yml/badge.svg)](https://github.com/pamagister/python-template-project/actions)
+[![GitHub release](https://img.shields.io/github/v/release/pamagister/python-template-project)](https://github.com/pamagister/python-template-project/releases)
+[![Read the Docs](https://readthedocs.org/projects/python-template-project/badge/?version=stable)](https://python-template-project.readthedocs.io/en/stable/)
+[![License](https://img.shields.io/github/license/pamagister/python-template-project)](https://github.com/pamagister/python-template-project/blob/main/LICENSE)
+[![GitHub issues](https://img.shields.io/github/issues/pamagister/python-template-project)](https://github.com/pamagister/python-template-project/issues)
+[![PyPI](https://img.shields.io/pypi/v/python-template-project)](https://pypi.org/project/python-template-project/)
+
+
+This template provides a solid foundation for your next Python project, incorporating best practices for testing, automation, and distribution. It streamlines the development process with a comprehensive set of pre-configured tools and workflows, allowing you to focus on writing code.
+
+## Installation
+
+Download from [PyPI](https://pypi.org/).
+
+💾 For more installation options see [install](docs/getting-started/install.md).
+
+```bash
+pip install python-template-project
+```
+
+Run GUI from command line
+
+```bash
+python-template-project-gui
+```
+
+## How to use this template
+
+🐍 For details, see the [Getting Started](docs/develop/01_getting_started_dev.md) guide.
+
+
+## Feature overview
+
+* 📦 **Package Management:** Utilizes [uv](https://docs.astral.sh/uv/getting-started/), an extremely fast Python package manager, with dependencies managed in `pyproject.toml`.
+* ✅ **Code Formatting and Linting:** Pre-commit hook with the [RUFF auto-formatter](https://docs.astral.sh/ruff/) to ensure consistent code style.
+* 🧪 **Testing:** Unit testing framework with [pytest](https://docs.pytest.org/en/latest/).
+* 📊 **Code coverage reports** using [codecov](https://about.codecov.io/sign-up/)
+* 🔄 **CI/CD:**  [GitHub Actions](https://github.com/features/actions) for automated builds (Windows, macOS), unit tests, and code checks.
+* 💾 **Automated Builds:** GitHub pipeline for automatically building a Windows executable and a macOS installer.
+* 💬 **Parameter-Driven Automation:**
+    * Automatic generation of a configuration file from parameter definitions.
+    * Automatic generation of a Command-Line Interface (CLI) from the same parameters.
+    * Automatic generation of CLI API documentation.
+    * Automatic generation of change log using **gitchangelog** to keep a HISTORY.md file up to date.
+* 📃 **Documentation:** Configuration for publishing documentation on [Read the Docs](https://about.readthedocs.com/) using [mkdocs](https://www.mkdocs.org/) .
+* 🖼️ **Minimalist GUI:** Comes with a basic GUI based on [tkinker](https://tkdocs.com/tutorial/index.html) that includes an auto-generated settings menu based on your defined parameters.
+* 🖥️ **Workflow Automation:** A `Makefile` is included to simplify and automate common development tasks.
+* 🛳️ **Release pipeline:** Automated releases unsing the Makefile `make release` command, which creates a new tag and pushes it to the remote repo. The `release` pipeline will automatically create a new release on GitHub and trigger a release on  [PyPI](https://pypi.org.
+    * **[setuptools](https://pypi.org/project/setuptools/)** is used to package the project and manage dependencies.
+    * **[setuptools-scm](https://pypi.org/project/setuptools-scm/)** is used to automatically generate the `_version.py` file from the `pyproject.toml` file.
+

python_template_project-0.1.19/docs/develop/01_getting_started_dev.md

@@ -0,0 +1,29 @@
+
+# Getting started developing
+
+## Setup your project development environment
+
+Getting started on developing your own project based on this template
+
+> **DO NOT FORK** this is meant to be used from **[Use this template](https://github.com/pamagister/python-template-project/generate)** feature.
+
+1. Click on **[Use this template](https://github.com/pamagister/python-template-project/generate)**
+3. Give a name to your project  
+   (e.g. `my_python_project` recommendation is to use all lowercase and underscores separation for repo names.)
+3. Wait until the first run of CI finishes  
+   (Github Actions will process the template and commit to your new repo)
+
+## Troubleshooting
+
+### Problems with release pipeline
+
+If you get this error below:
+```bash
+/home/runner/work/_temp/xxxx_xxx.sh: line 1: .github/release_message.sh: Permission denied
+```
+
+You have to run these commands in your IDE Terminal or the git bash and then push the changes.
+```bash
+git update-index --chmod=+x ./.github/release_message.sh
+```
+

python_template_project-0.1.19/docs/develop/naming_convention.md

@@ -0,0 +1,46 @@
+# Naming Conventions in Python Projects
+
+In Python projects, it's crucial to use consistent naming conventions to ensure code readability and maintainability. The choice between underscores (`_`) and hyphens (`-`) largely depends on the context.
+
+---
+
+## Underscores (`_`) – Snake_case
+
+Primarily use underscores **within your Python code** for multi-word names. This is known as `snake_case`.
+
+* **Python Package Names (Internal):** The importable name of your Python package (e.g., the folder under `src/`) should use underscores.
+    * **Example:** `src/my_python_package` is imported as `import my_python_package`.
+* **Module Names (.py files):** Python file names that are modules should also use underscores.
+    * **Example:** `my_module.py`, `data_processing.py`.
+* **Variables, Functions, and Methods:** Within your code, these names should follow `snake_case`.
+    * **Example:** `my_variable`, `calculate_total()`, `_private_function()`.
+
+---
+
+## Hyphens (`-`) – Kebab-case
+
+Primarily use hyphens **outside of your Python code** for filesystem, URL, and human-readable names. This is often referred to as `kebab-case`.
+
+* **PyPI Package Name (Project Name):** The name under which your project is published on PyPI and installed with `pip install` should use hyphens.
+    * **Example:** In `pyproject.toml`: `name = "my-python-project"`. Installation: `pip install my-python-project`.
+* **Main Project Folder / Repository Name:** The root folder of your project in the file system.
+    * **Example:** `my-python-project/`.
+* **Documentation Folders and Files (MkDocs, ReadTheDocs):** Folders and Markdown files within your documentation.
+    * **Example:** `docs/getting-started/installation-guide.md`.
+* **Command-Line Tools / Scripts:** Names for executable scripts you define in your `pyproject.toml` under `[project.scripts]`.
+    * **Example:** `my-cli-tool = "my_python_package.cli:main"`.
+
+---
+
+## Summary of Recommendations
+
+| Context                       | Recommended Convention | Example                          |
+| :---------------------------- | :--------------------- |:---------------------------------|
+| **Internal Python Name** | Underscores (`_`)      | `my_python_package`              |
+| **PyPI / Project Name** | Hyphens (`-`)          | `my-python-package`              |
+| **Module Filename** | Underscores (`_`)      | `my_module.py`                   |
+| **Repository/Root Folder** | Hyphens (`-`)          | `my-python-project/`             |
+| **Docs Folders/Files** | Hyphens (`-`)          | `getting-started/cli-usage.md`   |
+| **CLI Commands** | Hyphens (`-`)          | `my-cli-tool`                    |
+
+Consistently applying these rules significantly improves the clarity and professionalism of your Python project.

{python_template_project-0.1.15 → python_template_project-0.1.19}/docs/getting-started/install.md

@@ -1,45 +1,66 @@
 # Installation
 
 
+## 🐍 PyPI
 
-## 🐍 Install from PyPI 
+### Install the package from PyPI
+
+Download from [PyPI](https://pypi.org/):
 
 ```bash
-python -m pip install python_template_project
+pip install python-template-project
 ```
 
+### Run CLI from command line
+```bash
+python-template-project [OPTIONS] path/to/file
+```
 
-## 🔽 Download installer
+### Run GUI from command line
+```bash
+python-template-project-gui
+```
+
+## 🔽 Executable
+
+Download the latest executable:
 
 - [⬇️ Download for Windows](https://github.com/pamagister/python-template-project/releases/latest/download/installer-win.zip)
 - [⬇️ Download for macOS](https://github.com/pamagister/python-template-project/releases/latest/download/package-macos.zip)
 
 
+## 👩🏼‍💻 Run from source
 
-## Run from source
-
-### Run with CLI from source
+### Clone the repository
 
 ```bash
-python -m python_template_project.cli [OPTIONS] path/to/file
+git clone
 ```
 
+### Navigate to the project directory
 
-### Run with GUI from source
+```bash
+cd python-template-project
+```
+
+### Install dependencies
 
 ```bash
-python -m python_template_project.gui
+uv venv
+uv pip install -e .[dev,docs]
 ```
 
 
-## Run from command line:
+### Run with CLI from source
 
-### Run CLI from command line
 ```bash
-python-template-project [OPTIONS] path/to/file
+python -m python_template_project.cli [OPTIONS] path/to/file
 ```
 
-### Run GUI from command line
+
+### Run with GUI from source
+
 ```bash
-python-template-project-gui
+python -m python_template_project.gui
 ```
+

python_template_project-0.1.19/docs/index.md

@@ -0,0 +1,55 @@
+# Welcome to python-template-project
+
+A feature-rich Python project template with with auto-generated CLI, GUI and parameterized configuration.
+
+[![Github CI Status](https://github.com/pamagister/python-template-project/actions/workflows/main.yml/badge.svg)](https://github.com/pamagister/python-template-project/actions)
+[![GitHub release](https://img.shields.io/github/v/release/pamagister/python-template-project)](https://github.com/pamagister/python-template-project/releases)
+[![Read the Docs](https://readthedocs.org/projects/python-template-project/badge/?version=stable)](https://python-template-project.readthedocs.io/en/stable/)
+[![License](https://img.shields.io/github/license/pamagister/python-template-project)](https://github.com/pamagister/python-template-project/blob/main/LICENSE)
+[![GitHub issues](https://img.shields.io/github/issues/pamagister/python-template-project)](https://github.com/pamagister/python-template-project/issues)
+[![PyPI](https://img.shields.io/pypi/v/python-template-project)](https://pypi.org/project/python-template-project/)
+
+
+This template provides a solid foundation for your next Python project, incorporating best practices for testing, automation, and distribution. It streamlines the development process with a comprehensive set of pre-configured tools and workflows, allowing you to focus on writing code.
+
+## Installation
+
+Download from [PyPI](https://pypi.org/).
+
+💾 For more installation options see [install](getting-started/install.md).
+
+```bash
+pip install python-template-project
+```
+
+Run GUI from command line
+
+```bash
+python-template-project-gui
+```
+
+## How to use this template
+
+🐍 For details, see the [Getting Started](develop/01_getting_started_dev.md) guide.
+
+
+## Feature overview
+
+* 📦 **Package Management:** Utilizes [uv](https://docs.astral.sh/uv/getting-started/), an extremely fast Python package manager, with dependencies managed in `pyproject.toml`.
+* ✅ **Code Formatting and Linting:** Pre-commit hook with the [RUFF auto-formatter](https://docs.astral.sh/ruff/) to ensure consistent code style.
+* 🧪 **Testing:** Unit testing framework with [pytest](https://docs.pytest.org/en/latest/).
+* 📊 **Code coverage reports** using [codecov](https://about.codecov.io/sign-up/)
+* 🔄 **CI/CD:**  [GitHub Actions](https://github.com/features/actions) for automated builds (Windows, macOS), unit tests, and code checks.
+* 💾 **Automated Builds:** GitHub pipeline for automatically building a Windows executable and a macOS installer.
+* 💬 **Parameter-Driven Automation:**
+    * Automatic generation of a configuration file from parameter definitions.
+    * Automatic generation of a Command-Line Interface (CLI) from the same parameters.
+    * Automatic generation of CLI API documentation.
+    * Automatic generation of change log using **gitchangelog** to keep a HISTORY.md file up to date.
+* 📃 **Documentation:** Configuration for publishing documentation on [Read the Docs](https://about.readthedocs.com/) using [mkdocs](https://www.mkdocs.org/) .
+* 🖼️ **Minimalist GUI:** Comes with a basic GUI based on [tkinker](https://tkdocs.com/tutorial/index.html) that includes an auto-generated settings menu based on your defined parameters.
+* 🖥️ **Workflow Automation:** A `Makefile` is included to simplify and automate common development tasks.
+* 🛳️ **Release pipeline:** Automated releases unsing the Makefile `make release` command, which creates a new tag and pushes it to the remote repo. The `release` pipeline will automatically create a new release on GitHub and trigger a release on  [PyPI](https://pypi.org.
+    * **[setuptools](https://pypi.org/project/setuptools/)** is used to package the project and manage dependencies.
+    * **[setuptools-scm](https://pypi.org/project/setuptools-scm/)** is used to automatically generate the `_version.py` file from the `pyproject.toml` file.
+