fixed docs

Author: andreascaglioni

docs/docs_github.rst

@@ -1,33 +1,31 @@
 Documentation (GitHub Actions)
 ==============================
 
-This page explains how the repository builds the Sphinx documentation and publishes
-the generated HTML to GitHub Pages using GitHub Actions.
+This page explains how the repository builds the Sphinx documentation and publishes the generated HTML to GitHub Pages using GitHub Actions.
 
 The workflow does the following:
 
-- Whenever a commit is pushed to `main`, the workflow checks out the repository (manual dispatch is also supported).
-- Sets up Python and installs the ``docs`` dependencies from :file:`pyproject.toml`.
-- Builds HTML with ``sphinx-build`` into ``docs/_build/html``.
-- Uploads the built HTML as a Pages artifact and deploys it to GitHub Pages.
+1. Whenever a commit is pushed to `main`, the workflow checks out the repository (manual dispatch is also supported).
+2. Sets up Python and installs the ``docs`` dependencies from :file:`pyproject.toml`.
+3. Builds HTML with ``sphinx-build`` into ``docs/_build/html``.
+4. Uploads the built HTML as a Pages artifact and deploys it to GitHub Pages.
+
+.. note::
+
+    First ensure the documentation is built correctly locally. See the previous page :doc:`Documentation (local) <docs_local>`.
+
+
+.. note::
+    Best practice: do NOT commit generated files (``docs/_build``, ``docs/_autosummary``) to the repository.
+    Keep them in ``.gitignore`` and let CI produce the HTML.
+    If you plan to serve source HTML directly from the ``docs/`` folder (without a build step), then you'd need to commit generated files — but the current workflow builds on CI and deploys the result, so committing generated files is unnecessary.
 
 Repository setup (one-time)
 ---------------------------
 1. Ensure the repository has GitHub Pages enabled for the ``gh-pages`` site (no manual branch required when using the Pages actions). In repository Settings → Pages you should see the site status after the first successful run.
 2. No secret is required. The workflow uses the repository's built-in ``GITHUB_TOKEN`` permissions to publish pages.
 
-Local testing
--------------
-See the previous page :doc:`Local documentation <docs_local>` for additional local setup and testing instructions.
-
-Autosummary and generated files
--------------------------------
-- ``autosummary_generate = True`` is enabled in ``docs/conf.py``, so Sphinx will generate the ``_autosummary`` pages during the build.
-- Best practice: do NOT commit generated files (``docs/_build``, ``docs/_autosummary``) to the repository. Keep them in ``.gitignore`` and let CI produce the HTML. If you plan to serve source HTML directly from the ``docs/`` folder (without a build step), then you'd need to commit generated files — but the current workflow builds on CI and deploys the result, so committing generated files is unnecessary.
-
 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.
-
-The workflow will attempt to publish your Sphinx docs automatically when you push to ``main``.

docs/tests.rst

@@ -1,14 +1,13 @@
 Tests
 =====
 
-It is a good idea to run the tests after installation to make sure the library works.
+It is a good idea to run the tests right after installation to make sure the library works (see “Running the tests manually” below).
 
-Testing during development is essential for identifying issues early and ensuring that new features do not break existing functionality.
+Running tests frequently during development catches issues early, provide fast feedback during development, and make refactoring safer. They also serve as executable documentation of expected behavior, reducing the risk of shipping bugs.
 
-Automated tests provide confidence in code changes and help maintain a stable and reliable code base as the project evolves. In the next section we'll see how to automatically run tests whenever the repository is pushed to the remote using GitHub-Actions.
-
-Test-driven development is a software development approach where tests are written before the actual code. This process helps clarify requirements, ensures code correctness, and encourages modular design. By writing tests first, developers can catch bugs early and maintain a high level of code quality.
+Test-driven development (TDD) means writing a failing test before implementing functionality. This practice clarifies requirements, encourages small, focused changes and modular design, and helps prevent regressions as the codebase evolves.
 
+For information on running tests automatically in CI, see the “GitHub Actions workflow for testing” section below for details on the included workflow that runs on pushes and pull requests.
 
 Running the tests manually
 --------------------------
@@ -20,3 +19,9 @@ Run the full PyTest test suite with coverage:
    pytest -q --cov=python_project_template_AS --cov-report=term --cov-report=html
 
 Open ``htmlcov/index.html`` to view the coverage report.
+
+
+GitHub Actions workflow for testing
+-----------------------------------
+
+This project includes a CI workflow at ``.github/workflows/tests.yml`` that runs on pushes and pull requests. The workflow sets up one or more Python versions, installs the package and test dependencies, runs exact configuration used in this project.

docs/usage.rst

@@ -9,19 +9,19 @@ The following is a quick example for the Calculator API. It shows how to:
 
 .. code-block:: python
 
-    from python_project_template_AS import default_calculator, Operation
+    from python_project_template_AS import default_calculator, Operation  # import API
 
-    calc = default_calculator()
+    calc = default_calculator()  # create a calculator instance
 
-    print(calc.apply('add', 2, 3))  # -> 5
+    print(calc.apply('add', 2, 3))  # use built-in addition -> 5
 
-    f = calc.compose(['neg', 'sqr'])
-    print(f(-3))  # -> 9
+    f = calc.compose(['neg', 'sqr'])  # compose negation and squaring
+    print(f(-3))  # composed function applied -> 9
 
-    def inc(x):
+    def inc(x):  # define increment operation
         return x + 1
 
-    calc.register(Operation('inc', inc, arity=1), replace=True)
-    print(calc.apply('inc', 4))
+    calc.register(Operation('inc', inc, arity=1), replace=True)  # register new operation
+    print(calc.apply('inc', 4))  # apply new operation -> 5
 
 Find additional examples in ``examples/``.