docs: upgrade the docs to rely on bwa-aln-interactive in bioconda

Author: clintval

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,86 @@
+# 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.

docs/installation.md

@@ -2,13 +2,8 @@ name: prymer
 channels:
   - bioconda
   - conda-forge
+  - defaults
 dependencies:
-  # Python
-  - python>=3.11.*
-  - ruff>=0.2.1
-  - mypy>=1.8
-  - pytest>=8.0.0
-  - pytest-workflow=2.1.0
-  - poetry=1.7.1
-  - primer3=2.6.1
-  - pyproject_hooks=1.0.0
+  - bioconda::bwa-aln-interactive=0.7.18
+  - bioconda::primer3=2.6.1
+  - conda-forge::python>=3.11.*