update docs, README, example_2

Author: andreascaglioni

.gitignore

@@ -1,6 +1,7 @@
 # Virtual environments
 .venv/
 venv/
+.venv_test/
 ENV/
 env/
 

README.md

@@ -8,58 +8,49 @@
 
 
 # python-project-template — showcasing good software practices
-The library provides a small dependence-free Calculator API (Operation, OperationRegistry, Calculator) that can register and compose simple mathematical operations.
-This simple code is used to showcase some good coding practices.
+
+`python-project-template` is a small python project to showcase good programming and software practices such as testing, documentation, CI/CD.
+
+This project implements a small dependence-free Calculator API (Operation, OperationRegistry, Calculator) that can register and compose simple mathematical operations.
 
 ## Table of contents
 - [Features](#features)
 - [Installation](#installation)
-- [Quick usage](#quick-usage)
+- [Usage and Testing](#Usage-and-Testing)
 - [Examples & experiments](#examples--experiments)
 - [Documentation](#documentation)
-- [Running tests](#running-tests)
 - [Contributing](#contributing)
 - [License](#license)
 
-## Features
+## Features Highlights
 
-- **Argument validation** with type annotations and runtime checking using the ``typing`` module.
-- **Consistent error messages** for invalid operations and inputs via custom ``Exceptions``.
-- **Unit tests** with ``pytest``. Global testing variables set in `tests/convtest.py`.
-- **Example notebooks and scripts** for demonstration and exploration.
-- **Google-style documentation** generated with ``sphinx``.
-- **Pre-commit routine** configured in `.pre-commit-config.yaml`:
+- **Type-annotated API** with runtime argument validation.
+- **Custom exceptions** for clear error reporting.
+- **Comprehensive unit tests** using `pytest`.
+- **Google-style documentation** auto-generated with Sphinx.
+- **Pre-commit checks** and code formatting tools.
+- **CI/CD pipelines** for testing and docs via GitHub Actions.
 
-  - Code formatting with ``black``
-  - Linting with ``ruff-pre-commit``
-  - Type checking with ``mypy``
-  - Additional checks and fixes (trailing whitespace removal, enforcing empty line at EOF, YAML syntax checks, blocking large files) via ``pre-commit-hooks``
 
-- **Modern packaging** and easy installation using `pyproject.toml`.
-- **Automated test suite and coverage reporting** integrated with GitHub Actions; coverage reports can be published to GitHub Pages. Setup in `.github/workflows/tests.yml`.
-- **Automatic documentation build and deployment** to GitHub Pages with GitHub Actions. Setup in `.github/workflows/docs.yml`.
-- **Easy contribution workflow** for new features and improvements.
+See the [Documentation](#documentation) for a detailed list of features.
 
 ## Installation
 
 To install the latest release from TestPyPI, use:
 
 ```bash
-python3 -m venv .venv
-source .venv/bin/activate
-python -m pip install --upgrade pip
 pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple python-project-template-AS
 ```
 
-Alternatively, you can clone the repository, create a virtual environment (recommended), and install dependencies and an editable installation of `python-project-template`:
+Alternatively, you can clone the repository and install dependencies and an editable installation of `python-project-template-AS` with:
 
 ```bash
-git clone <https://github.com/andreascaglioni/python-project-template>
+git clone <https://github.com/andreascaglioni/python-project-template-AS>
 cd python-project-template
 pip install -e ".[dev]"
 ```
 
-## Quick usage
+## Usage and Testing
 
 The following is a quick example for the Calculator API.
 
@@ -74,7 +65,7 @@ print(calc.apply('add', 2, 3))  # -> 5
 
 # Compose unary operations into a Callable
 f = calc.compose(['neg', 'sqr'])
-print(f(3))  # -> 9
+print(f(-3))  # -> 9
 
 # Register a custom operation
 def inc(x):
@@ -84,28 +75,20 @@ calc.register(Operation('inc', inc, arity=1), replace=True)
 print(calc.apply('inc', 4))  # -> 5
 ```
 
-- `experiments/` — short runnable demos.
-- `notebooks/` — exploratory notebooks.
-
-## Documentation
-
-For detailed documentation, please visit our [GitHub Pages](https://andreascaglioni.github.io/your-repo-name/).
-
-To build the documentation locally:
+Find more examples in `examples/`.
 
-1. Ensure all dependencies for documentation (e.g., Sphinx) generation are installed, for example running ``pip install -e ".[docs]"``.
-2. Run the documentation build command (for example, ``make html``).
-3. Review the generated HTML in ``docs/_build/html``.
-
-## Running tests
-
-Run the full PyTest test suite with coverage:
+To run the tests:
 
 ```bash
-pytest -q --cov=python_project_template_AS --cov-report=term --cov-report=html
+pytest tests/
+pytest -v tests/  # verbose output
+pytest --cov=python_project_template_AS tests/  # show test coverage
 ```
 
-Open `htmlcov/index.html` to view the coverage report.
+## Documentation
+
+For detailed documentation, please visit our [GitHub Pages](https://andreascaglioni.github.io/your-repo-name/).
+
 
 ## Contributing
 
@@ -121,7 +104,7 @@ git push --set-upstream origin feat/your-feature
 ```
 
 Run `pip install -e .[dev]` to get development tools (pre-commit, black, ruff, mypy, pytest, ...).
-The pre-commit routine is called with `pre-commit run --all-files` before committing.
+Run the pre-commit routine with `pre-commit run --all-files` before committing.
 
 ## License
 

docs/docs_github.rst

@@ -18,19 +18,7 @@ Repository setup (one-time)
 
 Local testing
 -------------
-To build the docs locally (recommended before pushing):
-
-.. code-block:: bash
-
-	# create and activate a venv
-	python -m venv .venv
-	source .venv/bin/activate
-	python -m pip install --upgrade pip
-	# install docs dependencies
-	pip install -e ".[docs]"
-	# build
-	cd docs
-	sphinx-build -b html -a -E -W -T . _build/html
+See the previous page :doc:`Local documentation <docs_local>` for additional local setup and testing instructions.
 
 Autosummary and generated files
 -------------------------------
@@ -42,4 +30,4 @@ Troubleshooting
 - If builds fail due to missing packages, ensure :file:`pyproject.toml` contains the correct ``docs`` extras and that ``pip install -e ".[docs]"`` succeeds.
 - If the site does not appear after the workflow succeeds, check Settings → Pages to ensure the site is not blocked by organization policy.
 
-That's it — the workflow will publish your Sphinx docs automatically when you push to ``main``.
+The workflow will attempt to publish your Sphinx docs automatically when you push to ``main``.

docs/docs_local.rst

@@ -5,6 +5,7 @@ Good documentation is essential for code sustainability. It ensures that others
 
 To build the documentation for this project, follow these steps:
 
-1. Ensure all dependencies for documentation generation are installed, for example with ``pip install -e ".[docs]"``.
-2. Run the documentation build command (for example, ``make html``).
-3. Review the generated HTML in ``docs/_build/html``.
+1. Install documentation dependencies with ``pip install -e ".[docs]"``.
+2. Move to ``docs/`` (``cd docs``) and build the documentation ``make html``.
+
+The generated HTML is in ``docs/_build/html``.

docs/usage.rst

@@ -16,15 +16,12 @@ The following is a quick example for the Calculator API. It shows how to:
     print(calc.apply('add', 2, 3))  # -> 5
 
     f = calc.compose(['neg', 'sqr'])
-    print(f(3))  # -> 9
+    print(f(-3))  # -> 9
 
     def inc(x):
         return x + 1
 
     calc.register(Operation('inc', inc, arity=1), replace=True)
     print(calc.apply('inc', 4))
 
-Find additional examples in:
-
-- ``experiments/`` — short demos
-- ``notebooks/`` — exploratory notebooks
+Find additional examples in ``examples/``.

examples/example_2_replace_operation.py

@@ -16,9 +16,13 @@ def add_v1(a, b):
     def add_v2(a, b):
         return (a + b) * 10
 
-    calc.register(Operation(name="add", func=add_v1))
-    assert calc.apply("add", 1, 2) == 3
-
-    # replace existing operation
-    calc.register(Operation(name="add", func=add_v2), replace=True)
-    assert calc.apply("add", 1, 2) == 30
+    op_v1 = Operation(name="add", func=add_v1, arity=2)
+    calc.register(op_v1)
+    sum_1 = calc.apply("add", 1, 2)
+    print("calc.apply('add', 1, 2) =", sum_1)
+
+    # Replace existing operation adn recompute the sum
+    op_v2 = Operation(name="add", func=add_v2, arity=2)
+    calc.register(op_v2, replace=True)
+    sum_2 = calc.apply("add", 1, 2)
+    print("calc.apply('add', 1, 2) = ", sum_2)

src/python_project_template_AS/__init__.py

@@ -20,6 +20,7 @@
 from .registry import OperationRegistry
 from .calculator import Calculator
 from .utils import is_number
+from importlib.metadata import version
 
 __all__ = [
     "CalculatorError",
@@ -37,6 +38,7 @@
     "is_number",
 ]
 
+__version__ = version("python-project-template-AS")
 
 # Default registry pre-populated with a few convenience operations.
 _default_registry = OperationRegistry()