Add inline docstrings to workflow modules for automated documentation

[Copilot]

Summary

Adds inline documentation to SPIMquant's 8 Snakemake workflow modules using parseable docstrings. Documentation is designed to resist staleness and enable future automated docs generation.

Changes

Inline Docstrings

• Module-level docstrings in all .smk files describing purpose, workflow stages, and data types
• Rule-level docstrings for representative rules (~30 rules across all workflows)

Example from templatereg.smk:

"""
Template registration workflow for SPIMquant.

Handles complete registration pipeline from subject SPIM to template space.
Includes intensity correction, affine/deformable registration, label transformation, and QC.

Key workflow stages:
1. Intensity correction (N4 bias field correction)
2. Affine registration to template
3. Deformable registration refinement
4. Forward/inverse transformations
5. Label resampling and warping
"""

rule affine_reg:
    """Perform affine registration to template using greedy.
    
    Registers subject SPIM to template space using 12-DOF affine transformation.
    Uses NMI metric and outputs transformation matrix + warped image for QC.
    """

Workflow Files Documented

• templatereg.smk: Module + 7 rule docstrings
• segmentation.smk: Module + 5 rule docstrings
• import.smk: Module + 4 rule docstrings
• masking.smk: Module + 4 rule docstrings
• preproc_mri.smk: Module + 3 rule docstrings
• patches.smk: Module docstring
• common.smk: Module docstring
• groupstats.smk: Enhanced existing docstrings

Maintainability Approach

• Docstrings are embedded directly in code for easy maintenance
• Can be parsed programmatically for future automated documentation generation
• Avoids separate documentation files that can become outdated
• Follows agent instructions to use inline docstrings rather than separate docs pages

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[Docs] Document .smk Files: Purpose, Rule Types, and Example Rules</issue_title>
<issue_description>- For each major .smk file in the SPIMquant rules directory, document:

• Its high-level purpose
• A breakdown of the types of rules included (inputs/outputs, role in pipeline, file types handled, dependencies)
• Brief commentary/examples for several representative rules
• Present content as a set of docs pages, organized per .smk file, in docs/workflows/ or similar.
• Link to relevant DAG subgraphs/figures.</issue_description>

<agent_instructions>try to write docs so they don't easily get out of date -- eg include docstrings in each rule definition to describe indiv rules, as these can be parsed out later for docs generation. saem for a smk file altogether, can use docstring on top of file. don't include lists of rules as these will get out of date if not updated during development</agent_instructions>

Comments on the Issue (you are @copilot in this section)

• Fixes [Docs] Document .smk Files: Purpose, Rule Types, and Example Rules #100

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[akhanf]

The docstrings made on the .smk files are great, but all the new .md files can just be deleted, they will be too hard to revise for accuracy, maintain, and are too verbose..

[Copilot]

The docstrings made on the .smk files are great, but all the new .md files can just be deleted, they will be too hard to revise for accuracy, maintain, and are too verbose..

Done. All markdown files in docs/workflows/ have been deleted and the workflows section removed from docs/index.md. The docstrings in all .smk files remain intact for future automated docs generation. (commit 98017e1)