Release v0.17.4 (#115)

* chore: bump version refs to `0.17.4`

* docs: some more docs fixes

* Tweak README

* docs: tweaks

* ci: run doctests after unit tests + update contributions docs

* chore(deps): update dev. + docs dependencies + PDM update to `2.17.1`

* docs: docs tweaks

* chore: fix release date in citation file

* docs: update contributions RST + MD pages

.github/workflows/ci.yml

@@ -109,14 +109,14 @@ jobs:
         echo "GITHUB_PATH=$GITHUB_PATH"
         echo "GITHUB_ENV=$GITHUB_ENV"
 
-    - name: Lint + Run tests + Measure code coverage
+    - name: Lint + Run unit & acceptance tests + Measure code coverage
       run: |
         pdm use -f .venv
         pdm install -v -dGlint --no-self --no-isolation
         pdm run -v lint
-        pdm run -v doctests
         pdm install -v -dGtest --no-self --no-isolation
         pdm run -v pytest
+        pdm run -v doctests
 
     - name: Upload coverage reports to Codecov
       uses: codecov/codecov-action@v4.0.1

CITATION.cff

@@ -24,6 +24,6 @@ keywords:
   - real numbers
 
 license: MPL-2.0
-version: 0.17.3
-date-released: 2024-07-12
+version: 0.17.4
+date-released: 2024-07-26
 

CONTRIBUTING.md

@@ -30,7 +30,7 @@ This basically involves creating a project-specific SSH keypair - if you
 don't already have one - and adding it to GitHub. If you have done this
 successfully then this verification step should work:
 
-``` bash
+``` shell
 ssh -vT git@github.com
 ```
 
@@ -96,7 +96,7 @@ dependencies, and their sub-dependencies etc. This can be used to
 install all development dependencies, including the project itself, in
 editable mode where available:
 
-``` bash
+``` shell
 pdm install -v --dev
 ```
 
@@ -110,15 +110,15 @@ pdm install -v --dev
 If you don't wish to install any editable dependencies, including the
 project itself, you can use:
 
-``` bash
+``` shell
 pdm install -v --dev --no-editable --no-self
 ```
 
 The default lockfile can be updated with any and all upstream changes in
 the TOML-defined dependencies, but excluding any editable dependencies
 including the project itself, using:
 
-``` bash
+``` shell
 pdm update -v --dev --no-editable --no-self --update-all
 ```
 
@@ -128,7 +128,7 @@ staged and included in a commit.
 The lockfile can be exported in its entirety to another format, such as
 `docs/requirements.txt` using:
 
-``` bash
+``` shell
 pdm export -v -f requirements --dev -o docs/requirements.txt
 ```
 
@@ -147,14 +147,38 @@ For convenience different types of test targets are defined in the
 `unittests` for running unittests and measuring coverage, using `pytest`
 and the `pytest-cov` plugin:
 
-``` bash
+``` shell
 make lint
 make unittests
 make doctests
 ```
 
-Linting warnings should be addressed first. The doctests serve as
-acceptance tests, and are best run after the unit tests.
+Linting warnings should be addressed first, and any changes staged and
+committed.
+
+Unit tests can be run all at once using `make unittests` or individually
+using `pytest`, e.g. running the test class for the
+`~continuedfractions.lib.continued_fraction_rational` function:
+
+``` shell
+python -m pytest -sv tests/units/test_lib.py::TestContinuedFractionRational
+```
+
+> [!NOTE]
+> The `-s` option in the `pytest` command is to allow interactive
+> environments to be entered on errors, e.g. debugger breakpoints. The
+> default behaviour of [capturing console
+> input/output](https://docs.pytest.org/en/stable/how-to/capture-stdout-stderr.html#default-stdout-stderr-stdin-capturing-behaviour)
+> would otherwise prevent debuggers from being triggered.
+
+The doctests serve as acceptance tests, and are best run after the unit
+tests. They can be run all at once using `make doctests`, or
+individually by library using `python -m doctest`, e.g. running all the
+doctests in `~continuedfractions.sequences`:
+
+``` shell
+python -m doctest -v src/continuedfractions/sequences.py
+```
 
 ## Documentation
 
@@ -166,23 +190,28 @@ building and deployment steps for documentation are not automated in a
 CI pipeline, but are done manually - this will be addressed in future
 releases.
 
-The Sphinx documentation can be built locally on any branch from the
-**project root** using:
+The Sphinx documentation source pages and assets are contained in the
+`docs/` subfolder. The HTML pages can be built locally on any branch
+(from the project root) using:
 
-``` bash
+``` shell
 make -C docs html
 ```
 
-First, ensure that you have installed the docs Python requirements,
-which include all development dependencies, either via `pip`:
+The pages will be built inside `docs/html`, with the index/home page
+being `docs/html/index.html`.
+
+In order for this to work first ensure that you have installed the
+documentation Python requirements listed in `docs/requirements.txt`.
+This can be done either via `pip`:
 
-``` bash
+``` shell
 pip install -r docs/requirements.txt
 ```
 
 or via [PDM](https://pdm.fming.dev/latest/):
 
-``` bash
+``` shell
 pdm install -v --dev --no-editable --no-self
 ```
 
@@ -192,15 +221,13 @@ The CI/CD pipelines are defined in the [CI
 YML](https://github.com/sr-murthy/continuedfractions/blob/main/.github/workflows/ci.yml)
 and the [CodeQL Analysis
 YML](https://github.com/sr-murthy/continuedfractions/blob/main/.github/workflows/codeql-analysis.yml),
-and pipelines for all branches include a tests stage, consisting of Ruff
-linting, Python doctests, and unit tests, in that order. This will be
-amended in the future to ensure that tests are only run on updates to
-PRs targeting `main`, to avoid duplication on `main`.
+and, currently, pipelines for all branches include a tests stage that
+includes Ruff linting, unit tests, Python doctests, and in that order.
 
 ## Versioning and Releases
 
 The [PyPI package](https://pypi.org/project/continuedfractions/) is
-currently at version `0.17.3` - the goal is to use [semantic
+currently at version `0.17.4` - the goal is to use [semantic
 versioning](https://semver.org/) consistently for all future releases,
 but some earlier releases do not comply with strict semantic versioning.
 

README.md

@@ -30,7 +30,7 @@ See the [project docs](https://continuedfractions.readthedocs.io/en/latest/) for
 
 The `continuedfractions` package is designed for users interested in:
 
-* learning about and working with (finite) continued fractions as Python objects, in an intuitive object-oriented way
+* learning about and working with (finite, simple) continued fractions as Python objects, in an intuitive object-oriented way
 * exploring their key properties, such as elements/coefficients, convergents, semiconvergents, remainders, and others
 * operating on them as rationals and instances of the standard library [`fractions.Fraction`](https://docs.python.org/3/library/fractions.html#fractions.Fraction) class
 * making approximations of and experimental computations for irrational numbers