Modernize packaging/CI and overhaul docs for RTD rendering and CIGAR guidance

.flake8

@@ -0,0 +1,4 @@
+[flake8]
+exclude = docs
+extend-exclude = .ipynb_checkpoints
+max-line-length = 120

.github/workflows/ci.yml

@@ -0,0 +1,51 @@
+name: CI
+
+on:
+  push:
+    branches: ["main", "master", "publish-prep"]
+  pull_request:
+    branches: ["main", "master"]
+
+jobs:
+  test:
+    name: Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install ".[dev,io]"
+
+      - name: Run tests
+        run: pytest
+
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install project (dev+io)
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install ".[dev,io]"
+
+      - name: Run flake8
+        run: flake8 cigarmath tests

.gitignore

@@ -106,6 +106,13 @@ ENV/
 # mypy
 .mypy_cache/
 
+# ruff
+.ruff_cache/
+ruff_cache/
+
+# uv (if you start using uv lockfiles locally)
+uv.lock
+
 # IDE settings
 .vscode/
 .idea/

.readthedocs.yaml

@@ -0,0 +1,18 @@
+version: 2
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+
+sphinx:
+  configuration: docs/conf.py
+
+python:
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - dev
+        - io
+    - requirements: docs/requirements.txt

CONTRIBUTING.rst

@@ -15,7 +15,7 @@ Types of Contributions
 Report Bugs
 ~~~~~~~~~~~
 
-Report bugs at https://github.com/judowill/cigarmath/issues.
+Report bugs at https://github.com/DamLabResources/cigarmath/issues.
 
 If you are reporting a bug, please include:
 
@@ -102,9 +102,9 @@ Before you submit a pull request, check that it meets these guidelines:
 2. If the pull request adds functionality, the docs should be updated. Put
    your new functionality into a function with a docstring, and add the
    feature to the list in README.rst.
-3. The pull request should work for Python 3.5, 3.6, 3.7 and 3.8, and for PyPy. Check
-   https://travis-ci.com/judowill/cigarmath/pull_requests
-   and make sure that the tests pass for all supported Python versions.
+3. The pull request should work for the Python versions supported by
+   `pyproject.toml` (currently 3.8+). Check GitHub Actions on your PR and
+   make sure the tests pass for the full CI matrix.
 
 Tips
 ----
@@ -117,12 +117,11 @@ $ pytest tests.test_cigarmath
 Deploying
 ---------
 
-A reminder for the maintainers on how to deploy.
-Make sure all your changes are committed (including an entry in HISTORY.rst).
-Then run::
+A reminder for the maintainers on how to deploy a release.
 
-$ bump2version patch # possible: major / minor / patch
-$ git push
-$ git push --tags
+1. Update `version` in `pyproject.toml`.
+2. Update `HISTORY.md` (if you are maintaining a changelog for the release).
+3. Build the distribution and upload to PyPI (example)::
 
-Travis will then deploy to PyPI if tests pass.
+$ python -m build
+$ python -m twine upload dist/*

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022-present Will Dampier and DV Klopfenstein
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

PR.md

@@ -0,0 +1,82 @@
+## Title
+Modernize packaging/CI and overhaul docs for RTD rendering and CIGAR guidance
+
+## Summary
+- Modernizes project packaging and metadata by moving to `pyproject.toml`, removing legacy `setup.py`, and updating development requirements.
+- Adds/updates CI and documentation infrastructure (`.github/workflows/ci.yml`, `.readthedocs.yaml`, Sphinx config/requirements) for current Python and Read the Docs workflows.
+- Expands user-facing documentation substantially, including a practical `usage` guide and a new dedicated CIGAR format explainer page.
+- Normalizes API docstring examples across core modules so fixed-width alignment examples render correctly and consistently on RTD.
+- Updates tox matrix to current supported Python versions (`3.8`-`3.12`) to match project classifiers.
+- Applies a full repository flake8 cleanup across package and tests, addressing style debt and unused-symbol issues.
+
+## Commits Included (main...publish-prep)
+1. `864c0f2` modernizing
+2. `4418b42` fixing docs for fixed width setup
+3. `ed10800` fixes for sphinx warnings
+4. `60fe528` unpinning
+5. `a6b88ea` pointing at correct repo
+6. `dba9d6f` adding cigar explanation and basic usage
+7. `023158b` updating old tox
+8. `858c865` flake8 massive fix
+
+## Notable Changes by Area
+
+### Packaging and metadata
+- Added `pyproject.toml` with project metadata and dependency groups.
+- Removed legacy `setup.py`.
+- Consolidated dev tooling into the `dev` extra in `pyproject.toml` (retired `requirements_dev.txt`).
+- Updated package version metadata reference points in `cigarmath/__init__.py`.
+
+### CI and release/doc infrastructure
+- Added GitHub Actions workflow at `.github/workflows/ci.yml`.
+- Added Read the Docs config at `.readthedocs.yaml`.
+- Updated `tox.ini` env matrix to `py38, py39, py310, py311, py312, flake8`.
+
+### Documentation structure and quality
+- Expanded docs pages: `docs/api.rst`, `docs/installation.rst`, `docs/readme.rst`, `docs/history.rst`, `docs/index.rst`.
+- Added new CIGAR reference page: `docs/cigar.rst`.
+- Rewrote `docs/usage.rst` into a workflow-based guide with runnable examples and expected outputs.
+- Updated docs build requirements: `docs/requirements.txt`.
+- Tuned Sphinx config in `docs/conf.py` for stable rendering and warning cleanup.
+
+### API docstring rendering fixes
+- Updated fixed-width examples to explicit literal-block style in:
+  - `cigarmath/block.py`
+  - `cigarmath/cigarmath.py`
+  - `cigarmath/clipping.py`
+  - `cigarmath/inference.py`
+  - `cigarmath/mapping.py`
+  - `cigarmath/iterators.py`
+  - `cigarmath/combine.py`
+  - `cigarmath/pileup.py`
+  - `cigarmath/conversions.py`
+
+### Lint and style sweep
+- Ran `flake8` cleanup across `cigarmath/` and `tests/`.
+- Resolved unused-import/redefinition issues in public exports (`cigarmath/__init__.py`) and module imports.
+- Removed checkpoint artifact from lint surface (`.ipynb_checkpoints` excluded / cleaned).
+- Standardized formatting and whitespace across tests and core modules.
+
+## Diff Scope
+- **42 files changed**
+- **1476 insertions**, **831 deletions**
+
+## Test Plan
+- [x] Build docs locally:
+  - `python -m sphinx -b html docs docs/_build/html`
+- [x] Validate no Sphinx build warnings in latest pass.
+- [x] Run style checks:
+  - `flake8 cigarmath tests`
+- [ ] Run tox across available local interpreters:
+  - `tox -e py38,py39,py310,py311,py312,flake8`
+- [ ] Run unit tests directly:
+  - `pytest`
+
+## Risk / Reviewer Notes
+- Largest review surface is docs, packaging modernization, and the broad lint-driven formatting sweep.
+- Core behavioral intent should be unchanged; most additional churn is style/format and import hygiene.
+- Recommend reviewers focus on:
+  - Packaging metadata correctness (`pyproject.toml`)
+  - CI/tox Python version alignment
+  - RTD/Sphinx rendering behavior for fixed-width examples
+  - Spot-checking representative tests/modules touched by flake8 normalization

cigarmath/__init__.py

@@ -1,15 +1,15 @@
 """Top-level package for Cigar Math."""
 
+import importlib.metadata
+import importlib.util
+
 __author__ = """Will Dampier"""
 __email__ = "wnd22@drexel.edu"
-__version__ = "0.1.0"
-
 
 from .clipping import left_clipping
 from .clipping import right_clipping
 from .clipping import declip
 from .clipping import is_hard_clipped
-from .clipping import left_clipping
 from .clipping import softclipify
 
 
@@ -19,7 +19,6 @@
 from .block import query_offset
 from .block import query_block
 from .block import block_overlap_length
-from .block import reference_offset
 from .block import reference_mapping_blocks
 from .block import reference_deletion_blocks
 
@@ -35,7 +34,6 @@
 from .conversions import cigartuples2pairs
 
 from .conversions import msa2cigartuples
-from .conversions import softclipify
 
 from .cigarmath import collapse_adjacent_blocks
 
@@ -57,4 +55,57 @@
 from .rearrangement import format_read_rearrangement_summary
 from .rearrangement import rearrangement_segment_stream
 from .rearrangement import reference_lengths_from_pysam_header
-from .rearrangement import RearrangementEvent
+from .rearrangement import RearrangementEvent
+
+
+def _read_runtime_version() -> str:
+    try:
+        return importlib.metadata.version("cigarmath")
+    except importlib.metadata.PackageNotFoundError:
+        if importlib.util.find_spec("cigarmath") is not None:
+            return "0.0.0+uninstalled"
+        raise
+
+
+__version__ = _read_runtime_version()
+
+__all__ = [
+    "left_clipping",
+    "right_clipping",
+    "declip",
+    "is_hard_clipped",
+    "softclipify",
+    "reference_offset",
+    "reference_block",
+    "query_start",
+    "query_offset",
+    "query_block",
+    "block_overlap_length",
+    "reference_mapping_blocks",
+    "reference_deletion_blocks",
+    "inferred_query_sequence_length",
+    "inferred_reference_length",
+    "cigarstr2tup",
+    "cigartup2str",
+    "io",
+    "segments_to_binary",
+    "cigartuples2pairs",
+    "msa2cigartuples",
+    "collapse_adjacent_blocks",
+    "reference2query",
+    "query2reference",
+    "cigar_iterator",
+    "cigar_iterator_reference_slice",
+    "liftover",
+    "iterator_attach",
+    "combine_multiple_alignments",
+    "combine_adjacent_alignments",
+    "trim_alignment",
+    "depth",
+    "infer_rearrangements",
+    "format_read_rearrangement_summary",
+    "rearrangement_segment_stream",
+    "reference_lengths_from_pysam_header",
+    "RearrangementEvent",
+    "__version__",
+]