feat: use bwa-aln-interactive and upgrade developer's docs (#32)

Closes #5 Closes #30 Closes #27 This PR also: - Addresses improper installation of poetry. - Adds some polish to the main README and developer documentation. --------- Co-authored-by: Tim Fennell <[email protected]>
fulcrumgenomics · Oct 16, 2024 · d87e740 · d87e740
1 parent 8638e3b
commit d87e740
Show file tree

Hide file tree

Showing 12 changed files with 196 additions and 216 deletions.
diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
@@ -19,87 +19,43 @@ jobs:
         PYTHON_VERSION: ["3.11", "3.12"]
     steps:
       - uses: actions/checkout@v4
-      - name: Checkout fulcrumgenomics/bwa-aln-interactive
-        uses: actions/checkout@v4
-        with:
-          repository: fulcrumgenomics/bwa-aln-interactive
-          ref: main
-          path: bwa
-          fetch-depth: 0
 
       - name: Set up Python ${{ matrix.PYTHON_VERSION }}
         uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.PYTHON_VERSION }}
 
+      - name: Install and configure Poetry
+        uses: snok/install-poetry@v1
+        with:
+          version: ${{env.POETRY_VERSION}}
+          installer-parallel: true
+
       - name: Set up miniconda
         uses: conda-incubator/setup-miniconda@v3
         with:
-          miniforge-variant: Mambaforge
           miniforge-version: latest
-          channels: conda-forge,bioconda
+          channels: bioconda,conda-forge
           activate-environment: prymer
           environment-file: prymer.yml
           channel-priority: true
           auto-update-conda: true
           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: poetry run mkdocs build --strict
diff --git a/.gitignore b/.gitignore
@@ -1,3 +1,4 @@
+.DS_Store
 .vscode/
 
 # Byte-compiled / optimized / DLL files

diff --git a/README.md b/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
diff --git a/docs/index.md b/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)
 
diff --git a/docs/installation-and-developers-documentation.md b/docs/installation-and-developers-documentation.md
@@ -0,0 +1,92 @@
+# 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 virtualenvs.create false
+    ```
+
+6. Install `prymer` into the virtual environment:
+
+    ```console
+    poetry install
+    ```
+
+## Checking the Build
+
+Use `poetry` to test your code.
+
+```console
+poetry run pytest
+```
+
+Note that `poetry run pytest` will run `mypy` checks, `ruff` checks, `pytest` unit tests, and will provide a unit test coverage report.
+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.