Add a user-path decision guide and Python compatibility matrix to the Getting Started page #269
Description
A new user arriving at the docs faces the following questions with no clear answers:
Should I use pyOpenMS or the TOPP command-line tools?
Do I need to install the full C++ library to use Python?
Which Python versions are supported right now?
Is KNIME still actively supported or is Nextflow the recommended workflow engine?
What is the difference between openms.readthedocs.io and pyopenms.readthedocs.io?
Additionally, Python version compatibility is not stated clearly anywhere on the main docs landing page. This has been a recurring source of confusion and GitHub issues (#7874, #6199, #6163).
Proposed changes
1. Add a "Choose your path" decision flowchart or table on the Introduction page
A short table like the following (or an equivalent visual decision tree) would dramatically reduce friction:
| I want to… | Recommended path |
|---|---|
| Run a quick analysis without installing anything | WebApps |
| Write Python scripts for custom analysis | pyOpenMS |
| Run pre-built pipelines from the command line | TOPP Tools (CLI) |
| Build visual workflows with a GUI | KNIME or TOPPView |
| Deploy reproducible pipelines at scale | Nextflow |
| Extend OpenMS core algorithms | C++ library |
2. Add a Python version compatibility matrix
Add a clearly visible matrix near the top of both the main and pyOpenMS installation pages:
| Python version | Supported via PyPI | Supported via conda | Notes |
|---|---|---|---|
| 3.9 | ✓ | ✓ | |
| 3.10 | ✓ | ✓ | |
| 3.11 | ✓ | ✓ | |
| 3.12 | ✓ | ✓ | |
| 3.13 | ✗ | ✗ | Use nightly wheels |
This table (or equivalent) should be updated with every release and prominently linked from the homepage.
3. Clarify the relationship between the two documentation sites
Add a short notice at the top of the main docs page explaining:
The Python bindings (pyOpenMS) have their own dedicated documentation at pyopenms.readthedocs.io. If you are using OpenMS via Python, start there.
4. Add a minimal troubleshooting section
A "Common installation issues" section covering the three most frequently reported problems:
No matching wheel found (pip install pyopenms fails) → check Python version or use nightly
Apple Silicon (M1/M2) — no native ARM wheel; use Rosetta 2 or conda