feat!: rebuild py-ft as a pure-python toolkit over pysam + pyMA

.github/workflows/release-python-pyft.yml

@@ -0,0 +1,40 @@
+# Build and publish py-ft to PyPI.
+#
+# Triggered by a tag like `py-ft-v0.4.0`. Since py-ft is now a pure-Python
+# package (over pysam + molecular-annotation), this is a single universal
+# wheel + sdist — no per-platform matrix. Bump the version in
+# py-ft/pyproject.toml, then push the tag. Publish pyMA first: py-ft depends on
+# `molecular-annotation` from PyPI.
+#
+# Uses PyPI trusted publishing (OIDC) — no API token. Requires a matching
+# trusted publisher on PyPI for project `pyft` (owner/repo
+# fiberseq/fibertools-rs, workflow release-python-pyft.yml, no environment).
+name: release py-ft
+on:
+  push:
+    tags: ["py-ft-v*"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build-publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Build sdist + wheel
+        run: |
+          python -m pip install --upgrade build
+          python -m build py-ft --outdir dist
+      - name: Publish to PyPI (trusted publishing)
+        if: startsWith(github.ref, 'refs/tags/')
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          skip-existing: true

.readthedocs.yaml

@@ -8,16 +8,14 @@ sphinx:
 
 build:
   os: "ubuntu-22.04"
-  apt_packages:
-    - cmake
   tools:
     python: "3.10"
-    rust: "latest"
 
+# py-ft is now a pure-Python package (pysam + molecular-annotation), so the docs
+# build no longer needs Rust/cmake. Installing the package pulls its runtime
+# deps from PyPI so autodoc can import pyft.
 python:
   install:
     - requirements: py-ft/docs/requirements.txt
     - method: pip
       path: ./py-ft
-#conda:
-#    environment: py-ft/docs/environment.yml

py-ft/docs/api.rst

@@ -1,16 +1,11 @@
-
 API Reference
-=================
+=============
 
-.. automodule:: pyft
-   :members:
-   :undoc-members:
-   :show-inheritance:
-   :member-order: bysource
+``pyft.fiberdata``
+------------------
 
-.. automodule:: utils
+.. automodule:: pyft.fiberdata
    :members:
    :undoc-members:
    :show-inheritance:
    :member-order: bysource
-

py-ft/docs/conf.py

@@ -6,10 +6,9 @@
 import re
 import sys
 
-# import sphinx
-# import sphinx.ext.autosummary as autosummary
-# sys.path.insert(0, os.path.abspath("../"))
-sys.path.insert(0, os.path.abspath("../python/pyft"))
+# Put the package source on the path so autodoc can import `pyft` even when the
+# package isn't pip-installed (Read the Docs installs it; local builds may not).
+sys.path.insert(0, os.path.abspath("../python"))
 import pyft
 
 # -- Project information -----------------------------------------------------
@@ -27,16 +26,13 @@
 
 extensions = [
     "sphinx.ext.autodoc",
-    # "sphinx_autodoc_typehints",
+    "sphinx.ext.napoleon",
     "sphinx.ext.viewcode",
-    # "sphinx.ext.napoleon",
     "sphinx_rtd_theme",
     "sphinx.ext.intersphinx",
-    # "edit_on_github",
-    "nbsphinx",
 ]
 
-source_suffix = [".rst", ".py"]
+source_suffix = [".rst"]
 
 templates_path = ["_templates"]
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]

py-ft/docs/index.rst

@@ -1,8 +1,8 @@
 Getting started
----------------
+===============
 
-pyft: python bindings for fibertools-rs
----------------------------------------
+pyft: a fiber-seq inspection toolkit for Python
+-----------------------------------------------
 
 .. image:: https://readthedocs.org/projects/py-ft/badge/?version=latest
     :target: https://py-ft.readthedocs.io/en/latest/?badge=latest
@@ -12,22 +12,47 @@ pyft: python bindings for fibertools-rs
     :target: https://badge.fury.io/py/pyft
 
 
-**pyft** provides a python API for the rust library `fibertools-rs <https://github.com/fiberseq/fibertools-rs>`_. The inspiration for this API is to make analysis in python easier and faster; therefore, only extraction of data from a fiberseq bam is supported and not writing. 
+**pyft** is a lightweight toolkit for inspecting and visualizing `fiber-seq
+<https://github.com/fiberseq/fibertools-rs>`_ BAMs from Python. It reads a
+record with `pysam <https://pysam.readthedocs.io>`_ and decodes its fiber-seq
+annotations through the `molecular-annotation
+<https://pypi.org/project/molecular-annotation/>`_ library, then exposes them
+under the fiber-seq vocabulary: ``m6a``, ``cpg`` (5mC), ``nuc``, ``msp`` and
+``fire``. It is read/inspection-focused — for producing or editing fiber-seq
+annotations, use `fibertools-rs <https://github.com/fiberseq/fibertools-rs>`_.
 
 
 Install
 =======
 .. code-block:: bash
 
     pip install pyft
-
+
+The plotting helpers (``pyft.plot`` / ``pyft.utils`` and the ``fiberplot`` CLI)
+require extra dependencies:
+
+.. code-block:: bash
+
+    pip install "pyft[viz]"
+
+
+Quick example
+=============
+.. code-block:: python
+
+    from pyft import fetch
+
+    for fiber in fetch("fiberseq.bam"):
+        print(fiber.name, fiber.strand, "m6A:", len(fiber.m6a), "MSPs:", len(fiber.msp))
+
 
 Vignettes
 =========
-The `vignettes <vignettes/index.rst>`_ are a good place to start to understand the capabilities of pyft.
+The :doc:`vignettes <vignettes/index>` are a good place to start.
+
 
 Indices and tables
-==================
+===================
 
 * :ref:`genindex`
 * :ref:`modindex`
@@ -38,9 +63,7 @@ Indices and tables
     :hidden:
     :maxdepth: 2
     :caption: pyft
-    
+
     self
     api.rst
     vignettes/index.rst
-
-

py-ft/docs/requirements.txt

@@ -1,11 +1,4 @@
-sphinx_bootstrap_theme
 sphinx<7.0.0
-sphinx-autodoc-typehints
-#==1.23.0
 sphinx-rtd-theme==1.2.2
-lxml-html-clean
 docutils==0.18.1
 setuptools
-nbsphinx
-pypandoc_binary
-#sphinxawesome-theme