docs: use bwa-aln-interactive and upgrade developer's docs

.github/workflows/tests.yml

@@ -32,10 +32,18 @@ jobs:
         with:
           python-version: ${{ matrix.PYTHON_VERSION }}
 
+      - name: Install poetry
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install poetry==${{env.POETRY_VERSION}}
+
+      - name: Configure poetry
+        shell: bash
+        run: poetry config virtualenvs.in-project true
+
       - name: Set up miniconda
         uses: conda-incubator/setup-miniconda@v3
         with:
-          miniforge-variant: Mambaforge
           miniforge-version: latest
           channels: conda-forge,bioconda
           activate-environment: prymer
@@ -45,61 +53,19 @@ jobs:
           auto-activate-base: false
           python-version: ${{ matrix.PYTHON_VERSION }}
 
-      - name: Install fulcrumgenomics/bwa
-        shell: bash -l {0}
-        run: |
-          conda activate prymer
-          pushd bwa
-          make -j $(nproc)
-          cp bwa ${CONDA_PREFIX}/bin
-          popd
-
-      - name: Configure poetry and check lock file
-        shell: bash -l {0}
-        run: |
-          conda activate prymer
-          poetry config virtualenvs.in-project false
-          poetry check --lock
+      - name: Install the project's dependencies
+        shell: bash -el {0}
+        run: poetry install
 
-      - name: Poetry install
-        shell: bash -l {0}
-        run: |
-          conda activate prymer
-          poetry lock --no-update
-          poetry install --with dev
-
-      - name: Unit tests (with doctest and coverage)
-        shell: bash -l {0}
-        run: |
-          conda activate prymer
-          poetry run pytest --cov=prymer --cov-report=xml --cov-branch --doctest-plus --doctest-modules prymer tests
+      - name: Test the codebase
+        shell: bash -el {0}
+        run: poetry run pytest
 
       - name: Upload coverage reports to Codecov
         uses: codecov/[email protected]
         with:
           token: ${{ secrets.CODECOV_TOKEN }}
-
-      - name: Style checking
-        shell: bash -l {0}
-        run: |
-          conda activate prymer
-          poetry run ruff format --check
-
-      - name: Run lint
-        shell: bash -l {0}
-        run: |
-          conda activate prymer
-          poetry run ruff check
 
-      - name: Run mypy
-        shell: bash -l {0}
-        run: |
-          conda activate prymer
-          poetry run mypy
-
-      - name: Run docs
-        shell: bash -l {0}
-        run: |
-          conda activate prymer
-          set -euo pipefail
-          poetry run mkdocs build --strict
+      - name: Test building the documentation
+        shell: bash -el {0}
+        run: set -euo pipefail && poetry run mkdocs build --strict

README.md

@@ -1,44 +1,62 @@
 # Python Primer Design Library
 
 [![Python Versions][language-badge]][language-link]
-[![Code Style][code-style-badge]][code-style-link]
-[![Type Checked][type-checking-badge]][type-checking-link]
-[![PEP8][pep-8-badge]][pep-8-link]
-[![Code Coverage][code-coverage-badge]][code-coverage-link]
 [![License][license-badge]][license-link]
-
----
-
-[![Install with Bioconda][bioconda-badge]][bioconda-link]
-[![Bioconda][bioconda-dl-badge]][bioconda-dl-link]
-[![PyPI version][pypi-badge]][pypi-link]
-[![PyPI download total][pypi-downloads-badge]][pypi-downloads-link]
-[![Python package][python-package-badge]][python-package-link]
+[![MyPy Checked][type-checking-badge]][type-checking-link]
+[![Poetry][poetry-badge]][poetry-link]
+[![Ruff][ruff-badge]][ruff-link]
 
 [language-badge]:       https://img.shields.io/badge/python-3.11_|_3.12-blue
 [language-link]:        http://www.python.org/
-[code-style-badge]:     https://img.shields.io/badge/code%20style-black-000000.svg
-[code-style-link]:      https://black.readthedocs.io/en/stable/ 
-[type-checking-badge]:  http://www.mypy-lang.org/static/mypy_badge.svg
-[type-checking-link]:   http://mypy-lang.org/
-[pep-8-badge]:          https://img.shields.io/badge/code%20style-pep8-brightgreen.svg
-[pep-8-link]:           https://www.python.org/dev/peps/pep-0008/
-[code-coverage-badge]:  https://codecov.io/gh/fulcrumgenomics/prymer/branch/main/graph/badge.svg
-[code-coverage-link]:   https://codecov.io/gh/fulcrumgenomics/prymer
 [license-badge]:        http://img.shields.io/badge/license-MIT-blue.svg
 [license-link]:         https://github.com/fulcrumgenomics/prymer/blob/main/LICENSE
-[bioconda-badge]:       https://img.shields.io/badge/install%20with-bioconda-brightgreen.svg?style=flat
+[type-checking-badge]:  http://www.mypy-lang.org/static/mypy_badge.svg
+[type-checking-link]:   http://mypy-lang.org/
+[poetry-badge]:         https://img.shields.io/endpoint?url=https://python-poetry.org/badge/v0.json
+[poetry-link]:          https://python-poetry.org/
+[ruff-badge]:           https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json
+[ruff-link]:            https://docs.astral.sh/ruff/
+
+[![Install with Bioconda][bioconda-badge]][bioconda-link]
+[![PyPI version][pypi-badge]][pypi-link]
+
+[bioconda-badge]:       https://img.shields.io/badge/install%20with-bioconda-brightgreen.svg?label=Install%20with
 [bioconda-link]:        http://bioconda.github.io/recipes/prymer/README.html
-[bioconda-dl-badge]:    https://img.shields.io/conda/dn/bioconda/prymer.svg?label=Bioconda
-[bioconda-dl-link]:     https://anaconda.org/bioconda/prymer
-[pypi-badge]:           https://badge.fury.io/py/prymer.svg
+[pypi-badge]:           https://img.shields.io/pypi/v/prymer?label=Install%20with%20PyPi
 [pypi-link]:            https://pypi.python.org/pypi/prymer
-[pypi-downloads-badge]: https://img.shields.io/pypi/dm/prymer
+
+[![Bioconda][bioconda-dl-badge]][bioconda-dl-link]
+[![PyPI download total][pypi-downloads-badge]][pypi-downloads-link]
+
+
+[bioconda-dl-badge]:    https://img.shields.io/conda/dn/bioconda/prymer.svg?label=Bioconda%20downloads
+[bioconda-dl-link]:     https://anaconda.org/bioconda/prymer
+[pypi-downloads-badge]: https://img.shields.io/pypi/dm/prymer.svg?label=PyPi%20downloads
 [pypi-downloads-link]:  https://pypi.python.org/pypi/prymer
-[python-package-badge]: https://github.com/fulcrumgenomics/prymer/actions/workflows/publish_prymer.yml/badge.svg
-[python-package-link]:  https://github.com/fulcrumgenomics/prymer/actions/workflows/publish_prymer.yml
 
-## Quick setup
+[![tests][python-tests-badge]][python-tests-link]
+[![publish prymer][publish-prymer-badge]][publish-prymer-link]
+[![Code Coverage][code-coverage-badge]][code-coverage-link]
+
+[publish-prymer-badge]: https://github.com/fulcrumgenomics/prymer/actions/workflows/publish_prymer.yml/badge.svg
+[publish-prymer-link]:  https://github.com/fulcrumgenomics/prymer/actions/workflows/publish_prymer.yml
+[python-tests-badge]:   https://github.com/fulcrumgenomics/prymer/actions/workflows/tests.yml/badge.svg
+[python-tests-link]:    https://github.com/fulcrumgenomics/prymer/actions/workflows/tests.yml
+[code-coverage-badge]:  https://codecov.io/gh/fulcrumgenomics/prymer/branch/main/graph/badge.svg
+[code-coverage-link]:   https://codecov.io/gh/fulcrumgenomics/prymer
+
+## Recommended Installation
+
+The package `prymer` requires installation of [Primer3](https://github.com/primer3-org/primer3) and [interactive `bwa`](https://github.com/fulcrumgenomics/bwa-aln-interactive).
+
+To satisfy these requirements, it is recommended to install using [bioconda](https://bioconda.github.io/):
+
+```console
+mamba install -c bioconda prymer
+```
+
+## Development and Testing
 
-See [Installation](docs/installation.md).
+See the [developer's instructions][developers-instructions-link] for more information.
 
+[developers-instructions-link]: https://prymer.readthedocs.io/en/latest/installation-and-developers-documentation.html#installation-for-development

docs/index.md

@@ -4,7 +4,7 @@ Python Primer Design Library
 
 ## Documentation Contents
 
-* [Installation](installation.md)
+* [Installation](installation-and-developers-documentation.md)
 * [Overview](overview.md)
 * [API](reference/prymer/index.md)
 

docs/installation-and-developers-documentation.md

@@ -0,0 +1,93 @@
+# Installation and Developer's Documentation
+
+## Recommended Installation
+
+The package `prymer` requires installation of [Primer3](https://github.com/primer3-org/primer3) and [interactive `bwa`](https://github.com/fulcrumgenomics/bwa-aln-interactive).
+
+To satisfy these requirements, it is recommended to install using [bioconda](https://bioconda.github.io/):
+
+```console
+mamba install -c bioconda prymer
+```
+
+## Installation for Development and Release
+
+1. Install the environment manager [`mamba`](https://mamba.readthedocs.io/en/latest/installation/mamba-installation.html)
+2. Install the Python build tool [`poetry`](https://python-poetry.org/docs/#installing-with-the-official-installer)
+3. Create an environment with Python, [Primer3](https://github.com/primer3-org/primer3), and [interactive `bwa`](https://github.com/fulcrumgenomics/bwa-aln-interactive):
+
+    ```console
+    mamba env create -y -f prymer.yml
+    ```
+
+4. Activate the environment:
+
+    ```console
+    mamba activate prymer
+    ```
+
+5. Configure `poetry` to install into pre-existing virtual environments:
+
+    ```console
+    poetry config settings.virtualenvs.create false
+    ```
+
+6. Install `prymer` into the virtual environment:
+
+    ```console
+    poetry install
+    ```
+
+# Checking the Build
+
+Use `poetry` to format, lint, type-check, and test your code.
+
+Note that `poetry run pytest` will run `mypy` and `ruff` checks, `pytest` unit tests, and will provide a unit test coverage report.
+
+```console
+poetry run pytest
+```
+
+However, `pytest` will neither run the ruff formatter nor apply `ruff`'s automatic lint fixes, which can be done by calling `ruff` directly. 
+
+```console
+poetry run ruff format && poetry run ruff check --fix
+```
+
+# Building the Documentation
+
+Use `mkdocs` to build and serve the documentation.
+
+```console
+poetry run mkdocs build && poetry run mkdocs serve
+```
+
+# Creating a Release on PyPi
+
+1. Clone the repository recursively and ensure you are on the `main` (un-dirty) branch
+2. Checkout a new branch to prepare the library for release
+3. Bump the version of the library to the desired SemVer with `poetry version #.#.#`
+4. Commit the version bump changes with a Git commit message like `chore(release): bump to #.#.#`
+5. Push the commit to the upstream remote, open a PR, ensure tests pass, and seek reviews
+6. Squash merge the PR
+7. Tag the new commit on the main branch of the origin repository with the new SemVer
+
+> [!NOTE]
+> This project follows [Semantic Versioning](https://semver.org/).
+> In brief:
+> 
+> * `MAJOR` version when you make incompatible API changes
+> * `MINOR` version when you add functionality in a backwards compatible manner
+> * `PATCH` version when you make backwards compatible bug fixes
+
+GitHub Actions will take care of the remainder of the deployment and release process with:
+
+1. Unit tests will be run for safety-sake
+2. A source distribution will be built
+3. Multi-arch multi-Python binary distributions will be built
+4. Assets will be deployed to PyPi with the new SemVer
+5. A [Conventional Commit](https://www.conventionalcommits.org/en/v1.0.0/)-aware changelog will be drafted
+6. A GitHub release will be created with the new SemVer and the drafted changelog
+
+> [!IMPORTANT]
+> Consider editing the changelog if there are any errors or necessary enhancements.