Added documentation and bug fixes

Makefile

@@ -1,10 +1,13 @@
 .PHONY: setup \
 		clean-cache-temp-files \
-		doc \
+		lint code-check \
+		doc  \
 		pipeline all
 
 .DEFAULT_GOAL := all
 
+SRC_PROJECT_HOOKS ?= hooks
+
 setup:
 	@echo "Installing dependencies..."
 	@uv sync --all-extras
@@ -18,11 +21,25 @@ clean-cache-temp-files:
 	@find . -type f \( -name '*.pyc' -o -name '*.pyo' \) -delete
 	@echo "✅ Clean complete."
 
+lint:
+	@echo "Running lint checks..."
+	@uv run isort $(SRC_PROJECT_HOOKS)/
+	@uv run ruff check --fix $(SRC_PROJECT_HOOKS)/
+	@uv run ruff format $(SRC_PROJECT_HOOKS)/
+	@echo "✅ Linting complete."
+
+code-check:
+	@echo "Running static code checks..."
+	@uv run mypy $(SRC_PROJECT_HOOKS)/
+	@uv run complexipy -f $(SRC_PROJECT_HOOKS)/
+	@uv run bandit -r $(SRC_PROJECT_HOOKS)/
+	@echo "✅ Code and security checks complete."
+
 doc:
 	@echo "Serving documentation..."
 	@uv run mkdocs serve
 
-pipeline: clean-cache-temp-files
+pipeline: clean-cache-temp-files lint code-check
 	@echo "✅ Pipeline complete."
 
 all: setup pipeline doc

README.md

@@ -38,7 +38,7 @@ manage dependencies cleanly. Additionally, ensure that
 [`uv`](https://github.com/astral-sh/uv) is installed in your environment to handle
 grouped dependency installations.
 
-### 1. Generate Your Project
+1. Generate Your Project
 
 Use Cookiecutter to create a new project from the template:
 
@@ -48,7 +48,7 @@ cookiecutter https://github.com/danibcorr/python-project-template.git
 
 Follow the prompts to configure project metadata, package name, and other options.
 
-### 2. Install Dependencies
+2. Install Dependencies
 
 Activate your virtual environment and install all dependencies using the included
 `Makefile`:
@@ -60,7 +60,7 @@ make install
 This installs development, testing, and documentation tools as defined in
 `pyproject.toml`.
 
-### 3. Run the Pipeline
+3. Run the Pipeline
 
 Execute the quality pipeline, which includes linting, type checking, security analysis,
 complexity checks, and test execution:
@@ -69,7 +69,7 @@ complexity checks, and test execution:
 make pipeline
 ```
 
-### 4. Run the Full Workflow (Optional)
+4. Run the Full Workflow (Optional)
 
 To perform a complete setup including dependency installation, full quality checks, and
 local documentation preview:

docs/.nav.yml

@@ -1,7 +1,13 @@
 nav:
   - Home: index.md
-  - Documentation: content/
+  - Documentation:
+      - Overview: content/overview.md
+      - Getting Started: content/cookiecutter.md
+      - Makefile Commands: content/makefile-commands.md
+      - Configuration: content/pyproject-configuration.md
+      - Pre-commit Hooks: content/pre-commit-hooks.md
+      - CI/CD: content/ci-cd.md
 
 sort:
   ignore_case: true
-  type: alphabetical
+  type: alphabetical

docs/content/ci-cd.md

@@ -0,0 +1,72 @@
+# Continuous Integration and Continuous Deployment with GitHub Actions
+
+## Overview of the Automation Strategy
+
+The continuous integration and continuous deployment (CI/CD) process is implemented
+through GitHub Actions using a workflow definition located at
+`.github/workflows/workflow.yml`. This workflow is designed to automate, in a unified and
+reproducible manner, the validation, documentation generation, and release management
+phases of the project lifecycle. By integrating these activities into a single automated
+pipeline, the repository ensures consistency between code changes, documentation updates,
+and published releases, while reducing manual intervention and the risk of human error.
+
+## Workflow Architecture and Execution Logic
+
+The workflow is composed of several logically separated jobs, each responsible for a
+specific stage of the CI/CD process. These jobs are executed according to clearly defined
+triggering conditions, primarily based on repository events and branch context. The
+structure reflects a progressive validation model in which foundational checks are
+performed first, followed by documentation deployment and release creation when the code
+reaches a stable state.
+
+## Environment Setup and Dependency Initialization
+
+The initial job, referred to as the setup phase, is executed on every push and on every
+pull request. Its primary purpose is to establish a controlled and reproducible execution
+environment. During this phase, a Python runtime environment is provisioned, ensuring
+that subsequent jobs operate under consistent interpreter conditions. All dependencies
+defined under the `pipeline` group are then installed, which guarantees that the tools
+required for validation, documentation generation, and automation are available before
+any further processing occurs. This step functions as a foundational safeguard, as
+failures at this stage prevent downstream jobs from executing under incomplete or
+misconfigured conditions.
+
+## Documentation Build and Deployment on the Main Branch
+
+When changes are merged into the `main` branch, the workflow activates an additional job
+dedicated to documentation management. In this phase, the project documentation is built
+using MkDocs, a static site generator specifically designed for technical documentation.
+The resulting site is then automatically deployed to GitHub Pages, ensuring that the
+published documentation always reflects the current state of the main codebase.
+
+Version management of the documentation is handled through `mike`, which enables the
+coexistence of multiple documentation versions corresponding to different project
+releases. This approach allows users to consult documentation aligned with specific
+versions of the software, thereby improving traceability and long-term maintainability.
+The deployment process is fully automated and does not require manual approval once the
+workflow conditions are satisfied.
+
+## Automated Release Creation and Versioning
+
+Also restricted to the `main` branch, the release creation job formalizes the delivery of
+a new software version. During this stage, the workflow programmatically determines the
+current project version and uses this information to create a new GitHub release. Release
+notes are generated automatically, typically by aggregating relevant commit messages or
+changes since the previous release. This ensures that each release is consistently
+documented and that users have immediate access to a structured summary of modifications,
+enhancements, and fixes.
+
+By integrating release creation into the CI/CD pipeline, the workflow enforces a direct
+relationship between the main branch state and published artifacts, reducing
+discrepancies between source code and released versions.
+
+## GitHub Pages Configuration and Activation
+
+For the automated documentation deployment to function correctly, GitHub Pages must be
+configured to use GitHub Actions as its source. This configuration is performed within
+the repository settings by navigating to the Pages section and selecting GitHub Actions
+as the publication source. Once this setting is applied, every push to the `main` branch
+triggers the documentation build and deployment process defined in the workflow. As a
+result, the documentation site is continuously updated without requiring any additional
+manual steps, ensuring alignment between the repository content and its public technical
+documentation.

docs/content/cookiecutter.md

@@ -0,0 +1,53 @@
+# Cookiecutter
+
+## Introduction to Cookiecutter
+
+Cookiecutter is a command-line utility designed to generate project structures from
+predefined templates. It enables developers to rapidly scaffold new projects by prompting
+for configuration inputs and customizing the generated files according to the provided
+responses. This approach ensures consistency across projects, reduces setup time, and
+enforces best practices and organizational standards in project structure.
+
+## Configuration Variables
+
+The customization process is driven by a configuration file, typically named
+`cookiecutter.json`, which defines the variables that the template expects. Each variable
+corresponds to a specific aspect of the project, such as naming conventions, folder
+structures, or optional features. During project generation, Cookiecutter interactively
+prompts the user to provide values for these variables, thereby producing a project
+tailored to the user’s specifications. The main configuration variables include:
+
+| Variable                   | Description                                     | Example                        |
+| -------------------------- | ----------------------------------------------- | ------------------------------ |
+| `project_name`             | Name of the project                             | `my-project`                   |
+| `project_module_name`      | Name of the Python module                       | `src`                          |
+| `project_test_folder_name` | Name of the folder for tests                    | `tests`                        |
+| `project_version_python`   | Minimum required Python version                 | `3.11`                         |
+| `mkdocs_repo_url`          | URL of the repository for documentation         | `https://github.com/user/repo` |
+| `add_notebooks_folder`     | Option to include a notebooks folder            | `yes` / `no`                   |
+| `add_prompts_folder`       | Option to include a prompts folder              | `yes` / `no`                   |
+| `add_dev_container_folder` | Option to include a Dev Container configuration | `yes` / `no`                   |
+
+These variables enable fine-grained control over the structure and functionality of the
+generated project, accommodating different workflows and development environments.
+
+## Project Generation Workflow
+
+The process of generating a project using Cookiecutter is straightforward. The user
+executes the `cookiecutter` command with the URL or local path of the desired template
+repository. Cookiecutter then sequentially prompts the user to provide values for each
+configuration variable defined in `cookiecutter.json`. Once all responses are collected,
+the tool automatically creates a new project directory populated with files and folders
+customized according to the provided inputs.
+
+For example, executing:
+
+```bash
+cookiecutter https://github.com/danibcorr/python-project-template.git
+```
+
+initiates the generation process. The user answers the interactive prompts, specifying
+names, versions, and optional components. Upon completion, a fully scaffolded project
+appears, reflecting the selected options and ready for immediate development. This
+automated approach promotes reproducibility, reduces setup errors, and enforces a
+consistent organizational structure across multiple projects.