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

[JudoWill]

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. 7bde62d modernizing
2. 4655d0d fixing docs for fixed width setup
3. 58b00cd fixes for sphinx warnings
4. 0f75594 unpinning
5. 141913a pointing at correct repo
6. 33f2080 adding cigar explanation and basic usage
7. 491f8f3 updating old tox
8. 032dd86 flake8 massive fix
9. ca3b059 configuration updates
10. ddbd9ea late flake8s
11. f72c0c2 resolved rearrangement docs

Notable Changes by Area

Packaging and metadata

• Added pyproject.toml with project metadata and dependency groups.
• Removed legacy setup.py.
• Updated 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

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