update docs and README

Author: andreascaglioni

README.md

@@ -3,6 +3,8 @@
 [![Python](https://img.shields.io/badge/python-3.8%2B-blue.svg)](https://www.python.org/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
+
+
 # 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.
@@ -22,50 +24,48 @@ This simple code is used to showcase some good coding practices.
 
 - **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 :file:`tests/convtest.py`.
+- **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 :file:`.pre-commit-config.yaml`:
+- **Pre-commit routine** configured in `.pre-commit-config.yaml`:
 
   - 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 :file:`pyproject.toml`.
-- **Automated test suite and coverage reporting** integrated with GitHub Actions; coverage reports can be published to GitHub Pages. Setup in :file:`.github/workflows/tests.yml`.
-- **Automatic documentation deployment** to GitHub Pages with GitHub Actions. Setup in :file:`.github/workflows/docs.yml` [TODO].
+- **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.
 
 ## Installation
 
 Clone the repository, create a virtual environment (recommended), and install dependencies and an editable installation of `python-project-template`:
 
 ```bash
-git clone <repo-url>
+git clone <https://github.com/andreascaglioni/python-project-template>
 cd python-project-template
 python3 -m venv .venv
 source .venv/bin/activate
 python -m pip install --upgrade pip setuptools wheel
 pip install -e ".[dev]"
 ```
 
-This installs the package in editable mode and the development extras (pytest, pre-commit, formatting and linting tools) so you can run tests and linters.
-
 ## Quick usage
 
 The following is a quick example for the Calculator API.
 
 ```python
 from python_project_template import default_calculator, Operation
 
-# Create a default calculator (pre-populated with common ops)
+# Create a default calculator (pre-populated with common operations)
 calc = default_calculator()
 
-# Apply an operation
+# Apply an addition operation
 print(calc.apply('add', 2, 3))  # -> 5
 
-# Compose unary operations
+# Compose unary operations into a Callable
 f = calc.compose(['neg', 'sqr'])
 print(f(3))  # -> 9
 
@@ -86,11 +86,9 @@ print(calc.apply('inc', 4))  # -> 5
 
 For detailed documentation, please visit our [GitHub Pages](https://andreascaglioni.github.io/your-repo-name/).
 
-If you want to build and deploy the docs yourself via GitHub Actions, see `docs/README_DOCS_DEPLOY.md` for configuration and setup steps.
-
 ## Running tests
 
-Run the full test suite with coverage:
+Run the full PyTest test suite with coverage:
 
 ```bash
 pytest -q --cov=python_project_template --cov-report=term --cov-report=html
@@ -102,28 +100,24 @@ Open `htmlcov/index.html` to view the coverage report.
 
 ```
 src/python_project_template/      # Core library package
-  - calculator.py                 # Calculator API
-  - operations.py                 # Built-in operations
-  - registry.py                   # Operation registry
-  - exceptions.py                 # Custom error types
-  - utils.py                      # Utility functions
-experiments/                      # Example scripts
-notebooks/                        # Jupyter notebooks
+  calculator.py                   # Calculator API
+  operations.py                   # Built-in operations
+  registry.py                     # Operation registry
+  exceptions.py                   # Custom error types
+  utils.py                        # Utility functions
+examples/                         # Example usage of API
 tests/                            # Test suite
-docs/                             # Documentation
-.github/
-  workflows/
-    tests.yml                     # GitHub Actions workflow for automated testing and coverage reporting
-    docs.yml                      # GitHub Actions workflow for automated documentation and deployment
-pyproject.toml                    # Build/config file
-README.md                         # Project overview
-LICENSE                           # License info
+docs/                             # Documentation (Sphinx source)
+.github/workflows/                # CI workflows (tests, docs)
+pyproject.toml                    # Project configuration and packaging
+README.md                         # This file
+LICENSE                           # License text
 CITATION.cff                      # Citation metadata
 ```
 
 ## Contributing
 
-Contributions are welcome. A quick workflow:
+Contributions are welcome. Typical workflow:
 
 ```bash
 git checkout -b feat/your-feature
@@ -134,16 +128,13 @@ git push --set-upstream origin feat/your-feature
 # open a PR
 ```
 
-### Developer notes
-- Use `pip install -e .[dev]` to get dev tools (pre-commit, black, ruff, mypy).
-- Run `pre-commit run --all-files` before committing.
-- CI runs tests on Ubuntu for Python 3.9–3.12 and uploads HTML coverage.
+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.
 
 ## License
 
 This project is licensed under the MIT License — see the `LICENSE` file.
 
 ## Questions
 
-If you have questions or want help extending the project (docs, CI, or
-examples), open an issue or drop a message in the repo.
+If you have questions or want help extending the project (docs, CI, or examples), open an issue or drop a message in the repository.

docs/appendix.rst

@@ -27,5 +27,4 @@ This project is licensed under the MIT License — see the ``LICENSE`` file.
 Questions
 ---------
 
-If you have questions or want help extending the project (docs, CI, or examples),
-open an issue or create a discussion in the repository.
+If you have questions or want help extending the project (docs, CI, or examples), open an issue or drop a message in the repository.

docs/features.rst

@@ -7,15 +7,15 @@ This code is used to showcase a number of good software practices:
 - Consistent error messages for invalid operations and inputs via custom ``Exceptions``
 - Unit tests with ``pytest``. Use :file:`tests/convtest.py` to set global testing variables
 - Example notebooks and scripts
-- Google-style documentation with ``sphinx``
+- Google-style documentation generated with ``sphinx``
 - Pre-commit routine set up in file :file:`.pre-commit-config.yaml`. It includes:
 
   - Formatting with ``black``
   - Linting with ``ruff`` via pre-commit
   - Type checking with ``mypy``
-  - Additional checks and fixes (remove trailing whitespace, ensure one empty line at end of file, YAML syntax checks, prevent committing large files) with ``pre-commit-hooks``
+  - Additional checks and fixes (trailing whitespace removal, enforcing empty line at EOF, YAML syntax checks, blocking large files) via ``pre-commit-hooks``
 
 - Modern packaging, easy installation, and project settings with :file:`pyproject.toml`
 - Automated test suite and coverage reporting integrated with `GitHub Actions`; coverage reports can be published to `GitHub Pages`. See :file:`.github/workflows/tests.yml`
-- Automatic build and deployment of the documentation to `GitHub Pages` with GitHub Actions. See :file:`.github/workflows/docs.yml`
-- Easy contribution workflow.
+- Automatic documentation build and deployment to `GitHub Pages` with GitHub Actions. Setup in :file:`.github/workflows/docs.yml`
+- Easy contribution workflow for new features and improvements.

docs/installation.rst

@@ -5,9 +5,11 @@ Clone the repository, create a virtual environment (recommended), and install de
 
 .. code-block:: bash
 
-   git clone <repo-url>
+   git clone <https://github.com/andreascaglioni/python-project-template>
    cd python-project-template
    python3 -m venv .venv
    source .venv/bin/activate
    python -m pip install --upgrade pip setuptools wheel
    pip install -e ".[dev]"
+
+The editable installation automatically updates with the source code. It is useful for development because it allows skipping additional installations after source edits.

docs/structure.rst

@@ -10,15 +10,18 @@ The project has the following directory structure:
      registry.py                     # Operation registry
      exceptions.py                   # Custom error types
      utils.py                        # Utility functions
-   experiments/                      # Example scripts
-   notebooks/                        # Jupyter notebooks
+   exampoles/                        # Example usage of API
    tests/                            # Test suite
    docs/                             # Documentation
-   .github/
-     workflows/
-       tests.yml                     # GitHub Actions workflow for automated testing and coverage reporting
-       docs.yml                      # GitHub Actions workflow for automated documentation and deployment
-  pyproject.toml                    # Build/config file
-  README.md                         # Project overview
-  LICENSE                           # License info
-  CITATION.cff                      # Citation metadata
+   .github/workflows/
+     tests.yml                     # GitHub Actions workflow for automated testing and coverage reporting
+     docs.yml                      # GitHub Actions workflow for automated documentation and deployment
+   pyproject.toml                    # Build/config file
+   README.md                         # Project overview
+   LICENSE                           # License info
+   CITATION.cff                      # Citation metadata
+
+
+.. note::
+
+  Why is the module inside ``src/``? It prevents accidental imports from the working directory so your tests mirror real installs. This is a widely recommended pattern in the `Python Packaging User Guide <https://packaging.python.org/en/latest/tutorials/packaging-projects/#src-layout>`_.

docs/tests.rst

@@ -13,7 +13,7 @@ Test-driven development is a software development approach where tests are writt
 Running the tests manually
 --------------------------
 
-Run the full pytest test suite with coverage:
+Run the full PyTest test suite with coverage:
 
 .. code-block:: bash
 

docs/usage.rst

@@ -12,6 +12,7 @@ The following is a quick example for the Calculator API. It shows how to:
     from python_project_template import default_calculator, Operation
 
     calc = default_calculator()
+
     print(calc.apply('add', 2, 3))  # -> 5
 
     f = calc.compose(['neg', 'sqr'])