Improvements in the documentation

.gitignore

@@ -0,0 +1,10 @@
+.venv/
+.DS_Store
+.idea/
+.vscode/
+.pytest_cache/
+.coverage
+.coverage.*
+.coverage.*.*
+.coverage.*.*.*
+.coverage.*.*.*.*

docs/_static/custom.css

@@ -0,0 +1,116 @@
+/* Custom styling for quantms documentation */
+
+/* Parameters table enhancement */
+.parameter-table {
+    border: 1px solid #e2e8f0;
+    border-radius: 8px;
+    overflow: hidden;
+    margin: 20px 0;
+    box-shadow: 0 1px 3px rgba(0, 0, 0, 0.1);
+}
+
+.parameter-table th {
+    background: linear-gradient(135deg, #6366f1 0%, #8b5cf6 100%);
+    color: white;
+    font-weight: bold;
+    text-align: center;
+    padding: 12px 8px;
+}
+
+.parameter-table td {
+    padding: 10px 8px;
+    border-bottom: 1px solid #f1f5f9;
+    vertical-align: top;
+}
+
+.parameter-table tr:nth-child(even) {
+    background-color: #f8fafc;
+}
+
+.parameter-table tr:hover {
+    background-color: #e2e8f0;
+    transition: background-color 0.2s ease;
+}
+
+/* Code highlighting in parameters */
+.parameter-table code {
+    background: #1e293b;
+    color: #f1f5f9;
+    padding: 2px 6px;
+    border-radius: 4px;
+    font-size: 11px;
+    font-weight: 500;
+}
+
+/* Navigation buttons enhancement */
+.nav-button {
+    transition: all 0.2s ease;
+    box-shadow: 0 1px 3px rgba(0, 0, 0, 0.1);
+}
+
+.nav-button:hover {
+    transform: translateY(-2px);
+    box-shadow: 0 4px 12px rgba(0, 0, 0, 0.15);
+}
+
+/* Section headers enhancement */
+.section-header {
+    position: relative;
+    overflow: hidden;
+}
+
+.section-header::before {
+    content: '';
+    position: absolute;
+    top: 0;
+    left: -100%;
+    width: 100%;
+    height: 100%;
+    background: linear-gradient(90deg, transparent, rgba(255, 255, 255, 0.2), transparent);
+    transition: left 0.5s;
+}
+
+.section-header:hover::before {
+    left: 100%;
+}
+
+/* Responsive design for navigation grid */
+@media (max-width: 768px) {
+    .nav-grid {
+        grid-template-columns: 1fr;
+        gap: 8px;
+    }
+
+    .parameter-table {
+        font-size: 12px;
+    }
+
+    .parameter-table th,
+    .parameter-table td {
+        padding: 8px 4px;
+    }
+}
+
+/* Enhanced tips and notes */
+.admonition.tip {
+    border-left: 4px solid #10b981;
+    background: linear-gradient(135deg, #ecfdf5 0%, #f0fdf4 100%);
+    border-radius: 8px;
+    padding: 16px;
+    margin: 20px 0;
+}
+
+.admonition.tip .admonition-title {
+    color: #059669;
+    font-weight: bold;
+    margin-bottom: 8px;
+}
+
+/* Search highlight enhancement */
+mark {
+    background: linear-gradient(135deg, #fef3c7 0%, #fde047 100%);
+    padding: 2px 4px;
+    border-radius: 3px;
+    color: #92400e;
+    font-weight: 500;
+}

docs/capabilities.rst

@@ -0,0 +1,34 @@
+What you can do with quantms (and when features arrived)
+========================================================
+
+This page summarizes key capabilities of quantms and references the version they were introduced in. Links point to the corresponding release notes.
+
+.. list-table:: Capabilities timeline
+   :header-rows: 1
+   :widths: 40 20 40
+
+   * - Capability
+     - Introduced in
+     - Notes
+   * - DDA-LFQ workflow
+     - 1.0.0
+     - Label-free quantification; OpenMS-based quantification. See `Release 1.0.0 <https://github.com/bigbio/quantms/releases/tag/1.0.0>`_.
+   * - Isobaric TMT workflow
+     - 1.2.0
+     - TMT reporter quantification and MSstats(TMT) export. See `Release 1.2.0 <https://github.com/bigbio/quantms/releases/tag/1.2.0>`_.
+   * - DIA workflow (DIA-NN based)
+     - 1.3.0
+     - DIA identification/quantification and exports to MSstats and Triqler. See `Release 1.3.0 <https://github.com/bigbio/quantms/releases/tag/1.3.0>`_.
+   * - Conda disabled by default
+     - 1.4.0
+     - Container-first execution (Docker/Singularity/Podman). See `Release 1.4.0 <https://github.com/bigbio/quantms/releases/tag/1.4.0>`_.
+   * - quantms-rescoring (DeepLC/MS2PIP integration)
+     - 1.5.0
+     - Optional ML-based rescoring features for improved identifications. See `Release 1.5.0 <https://github.com/bigbio/quantms/releases/tag/1.5.0>`_.
+   * - 1.6.0 highlights
+     - 1.6.0
+     - AlphaPeptDeep integration into quantms-rescoring. See `Release 1.6.0 <https://github.com/bigbio/quantms/releases/tag/1.6.0>`_.
+
+.. note:: This table is intentionally succinct. Consult the GitHub `Releases page <https://github.com/bigbio/quantms/releases>`_ for detailed, authoritative notes.
+
+

docs/comparison.rst

@@ -0,0 +1,67 @@
+How quantms compares to other tools
+===================================
+
+The following table highlights key differences between quantms and commonly used proteomics tools. This is a high-level, opinionated comparison; each tool evolves quickly, so always consult upstream documentation for the latest details.
+
+.. list-table:: Feature comparison
+   :header-rows: 1
+   :widths: 26 12 12 12 16 22
+
+   * - Feature
+     - quantms
+     - MaxQuant
+     - DIA-NN
+     - FragPipe
+     - ProteomeDiscoverer
+   * - Workflow type
+     - Nextflow pipeline (cloud/on-prem)
+     - Desktop/CLI app
+     - Desktop/CLI app
+     - Orchestrated CLI (Philosopher + tools)
+     - Commercial GUI
+   * - Acquisition support (DDA/DIA/Isobaric)
+     - Yes/Yes/Yes
+     - Yes/No/Yes (TMT)
+     - No/Yes/Partial (channels via DIA)
+     - Yes/Partial/Yes (TMT)
+     - Yes/Partial/Yes (TMT)
+   * - Multiple search engines
+     - Yes (MSGF+, Comet, SAGE)
+     - Primarily Andromeda
+     - DIA-focused scoring
+     - Yes (MSFragger + extras)
+     - Yes (via nodes, licensed add-ons)
+   * - Rescoring with ML (DeepLC/MS2PIP)
+     - Integrated (quantms-rescoring)
+     - Limited
+     - Built-in DIA rescoring
+     - Optional (Percolator/others)
+     - Optional (nodes)
+   * - Reproducibility (containers)
+     - First-class (Docker/Singularity/Podman)
+     - Not container-native
+     - Not container-native
+     - Can be containerized
+     - Not container-native
+   * - Standard outputs (mzTab/MSstats/Triqler)
+     - Yes
+     - mzTab (via converters), limited MSstats
+     - MSstats ready (DIA)
+     - Yes (via export)
+     - Via nodes
+   * - Scalability (HPC/cloud)
+     - Built-in via Nextflow
+     - Limited
+     - Limited
+     - Moderate (parallelizable steps)
+     - Limited
+   * - License
+     - Open source
+     - Free for acad., source-available parts
+     - Free for acad.
+     - Open source (core components)
+     - Commercial
+
+.. note:: This comparison focuses on workflow orchestration, reproducibility, and standardized outputs. It does not capture every feature (e.g., PTM localization, library building specifics, GUI convenience).
+
+

docs/conf.py

@@ -23,7 +23,7 @@
 author = 'daichengxin, jpfeuffer, timosachenberg, ypriverol'
 
 # The full version, including alpha/beta/rc tags
-release = '1.5.0'
+release = '1.6.0'
 
 
 # -- General configuration ---------------------------------------------------
@@ -60,6 +60,11 @@
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ['_static']
 
+# Custom CSS files to include
+html_css_files = [
+    'custom.css',
+]
+
 if os.environ.get("READTHEDOCS") == "True":
     # If we are building on ReadTheDocs, we need to download the output file
     # from the GitHub repository.

docs/contact.rst

@@ -14,7 +14,7 @@ How and when to contact us where
     just use the guidelines here and we will redirect you.
 
 
-.. |Get help on Slack| image:: http://img.shields.io/badge/slack-nf--core%20%23quantms-4A154B?labelColor=000000&logo=slack
+.. |Get help on Slack| image:: https://img.shields.io/badge/slack-nf--core%20%23quantms-4A154B?labelColor=000000&logo=slack
                    :target: https://nfcore.slack.com/channels/quantms
 
 .. |Report Issue| image:: https://img.shields.io/github/issues/bigbio/quantms

docs/dev.rst

@@ -1,11 +1,11 @@
 Information on development and how to get involved
 ==================================================
 
-Development happens exclusively and publicly on GitHub. The main repo is at bigbio/quantms with a fork at nf-core.
-The pipeline is written according to nf-core standards with all its continuous testing and DSL2 syntax.
+Development happens exclusively and publicly on GitHub. The main repo is at `bigbio/quantms <https://github.com/bigbio/quantms>`_ with a fork at nf-core.
+The pipeline is written according to nf-core standards with continuous testing and DSL2 syntax.
 Contributions are always welcome by forking the main repo on your GitHub account, creating a branch with
 a meaningful name and opening a PR when all the needed commits were made.
 The PR will then undergo manual review and continuous integration on test data, so make sure the
 test profiles pass on your local setup at least.
 
-TODO link to nf-core material on contributions
+See `nf-core contributing guide <https://nf-co.re/contributing>`_ for general contribution guidelines, and our repository's ``CONTRIBUTING.md`` for project-specific details.

docs/dia.rst

@@ -39,7 +39,7 @@ In order to analyze the DIA dataset the pipeline needs the acquisition method pr
 
 Similarly to the DDA workflow (see :doc:`lfq`, :doc:`iso`), we aim to make DIA-NN parallelize and distribute most of the tasks in the cluster.
 
-The first step of the workflow, translate the SDRF parameters into DIA-NN configuration parameters, including port-translation modification, enzyme, etc. For the developers and bioinformaticians, the details can be found in `diann to parameters <https://github.com/bigbio/quantms/blob/dev/bin/prepare_diann_parameters.py>`_ .
+The first step of the workflow translates the SDRF parameters into DIA-NN configuration parameters, including post-translation modifications, enzyme, etc. For developers and bioinformaticians, details can be found in `diann to parameters <https://github.com/bigbio/quantms/blob/dev/bin/prepare_diann_parameters.py>`_.
 
 The second step of the workflow, generate an in-silico spectral library from a FASTA sequence database if predefined transition libraries are not provided.
 The current step is run with the following parameters than can be changed in the commandline:
@@ -88,19 +88,26 @@ The last step of the workflow, summaries the information and then generates repo
 
 **Match between runs (MBR)**: In MBR is allowed, peptides identified by tandem mass spectra in one run are transferred to another by inference based on m/z, charge state, retention time, and ion mobility when applicable. This is done manually.
 
+.. note:: For DIA analyses using DIA-NN, prefer contaminants with UniProt descriptions that include gene names (e.g., ``contaminants-202105-uniprot-description.fasta``). This enables correct gene grouping in DIA-NN. See :doc:`protein_database` and the dataset listing `quantms-test-datasets/databases <https://github.com/bigbio/quantms-test-datasets/tree/quantms/databases>`__.
+
 MSstats
 ------------
 
-The output of DIA-NN is exported to MSstats for the downstream analysis by `diann to msstats <https://github.com/bigbio/quantms/blob/dev/bin/diann_convert.py>`_. you can read more about MSstats in :doc:`msstats`.
+The output of DIA-NN is exported to MSstats for downstream analysis by `diann to msstats <https://github.com/bigbio/quantms/blob/dev/bin/diann_convert.py>`_. You can read more about MSstats in :doc:`msstats`.
 
 Triqler
 ------------
 
-The output of DIA-NN is exported to Triqler for the downstream analysis, you can read more about Triqler in :doc:`triqler`.
-The `searchScore` is computed by the dia converter as 1-Q.value. The details can be found `diann to triqler <https://github.com/bigbio/quantms/blob/dev/bin/diann_convert.py>`_.
+The output of DIA-NN is exported to Triqler for downstream analysis; you can read more about Triqler in :doc:`triqler`.
+The `searchScore` is computed by the DIA converter as 1 - Q.value. Details can be found in `diann to triqler <https://github.com/bigbio/quantms/blob/dev/bin/diann_convert.py>`_.
+
+Relevant parameters
+--------------------
+
+- See `DIA-NN <parameters.html#dia-nn>`_ for options such as ``--mass_acc_automatic``, ``--scan_window``, ``--diann_speclib``, ``--diann_normalize``, and mzTab export via ``--enable_diann_mztab``.
 
 Important technical notes
---------------------------
+---------------------------
 
 By 2022, the quantms DIA workflow based on DIA-NN has the following drawbacks:
 

docs/fdr.rst

@@ -34,8 +34,7 @@ therefore this usually improved estimate is used when Percolator was chosen.
 .. warning:: Choosing peptide-level FDR with Percolator will discard all but the best PSM per peptide. Use with caution
     if you need full traceability.
 
-When using OpenMS' distribution-fitting approach, a standard formula for FDR calculation is used
-(TODO add formula) and is currently only available for the PSM level.
+When using OpenMS' distribution-fitting approach, a standard formula for FDR calculation is used at the PSM level.
 
 The FDR filtering at peptide spectrum match (PSM) level is currently always applied at the single file level.
 We argue that experiment-wide FDR control at the end of the workflow on the protein level is sufficient to limit error

docs/formats.rst

@@ -5,11 +5,13 @@ The quantms is natively based on HUPO-PSI standard file formats:
 
 - `mzML <https://www.psidev.info/mzML>`_: The mzML format is an open, XML-based format for mass spectrometer output files, developed with the full participation of vendors and researchers in order to create a single open format that would be supported by all software.
 
-- `mzTab <https://www.psidev.info/mztab>`_: mzTab is intended as a lightweight supplement to the existing standard mzML to store and represent peptide and protein and identifications together with experimental metadata and basic quantitative information.
+.. _mztab:
+
+- `mzTab <https://www.psidev.info/mztab>`__: mzTab is intended as a lightweight supplement to the existing standard mzML to store and represent peptide and protein identifications together with experimental metadata and basic quantitative information.
 
 - `sdrf <https://github.com/bigbio/proteomics-metadata-standard>`_: The SDRF-Proteomics format describes the sample characteristics and the relationships between samples and data files included in a dataset. The information in SDRF files is organised so that it follows the natural flow of a proteomics experiment.
 
-Apart of this three main file formats, additionally, multiple file formats are used within the workflow between steps and as a final output for downstream analysis including: idXML, consensusXML, MSstats output, etc.
+Apart from these three main file formats, multiple additional formats are used within the workflow between steps and as final outputs for downstream analysis, including: idXML, consensusXML, MSstats output, etc.
 
 Input formats
 ---------------------------
@@ -54,11 +56,10 @@ divided into two categories:
     the MSstats parameters (see the parameter documentation (TODO link) and the chapter on :doc:`MSstats <msstats>` for further
     details).
 
-.. important:: Unequal fractionation's are not supported yet, please remove superfluous fractions in all samples
-    if a run failed or was discarded.
+.. important:: Unequal fractionations are supported from version 1.5.0 onwards.
 
 .. important:: When multiple conditions are under study which cannot be reliably aligned or compared (e.g., due to
-    different instruments, chromatographies, fractionation's, and/or quantification strategies), the user should create
+    different instruments, chromatographies, fractionations, and/or quantification strategies), the user should create
     multiple SDRFs (one for each experiment).
 
 - ``characteristics[biological replicate]``:
@@ -79,7 +80,12 @@ If RAW files are provided, the first step of the identification pipeline
 `converts them into mzML <https://quantms.readthedocs.io/en/latest/identification.html#mass-spectra-processing-raw-conversion>`_.
 In addition, bruker ``.d`` data format is also supported in DIA subworkflow.
 
-.. important:: If you want to load local input spectra files instead of from SDRF or Experimental Design file. Please set `--root_dir` and `--local_input_type` (default mzML) parameters.
+.. important:: If you want to load local input spectra files instead of from SDRF or Experimental Design file, please set `--root_folder` and `--local_input_type` (default: mzML).
+
+Relevant parameters
+-------------------
+
+- See `Input/output options <parameters.html#input-output-options>`_ for ``--input``, ``--outdir``, ``--root_folder``, ``--local_input_type``.
 
 Protein databases
 ~~~~~~~~~~~~~~~~~~
@@ -128,6 +134,8 @@ Multiple files from OpenMS ecosystem are use within quantms to store intermediat
     An xml-based file format to store PSMs, peptide, and protein evidences. More information about the idXML can be
     `found here <https://abibuilder.cs.uni-tuebingen.de/archive/openms/Documentation/nightly/html/classOpenMS_1_1IdXMLFile.html>`__.
 
+.. _consensusxml:
+
 - consensusXML:
     An xml-based file format that extends idXML to include quantification data across multiple runs.
     More information about the consensusXML can be
@@ -136,9 +144,16 @@ Multiple files from OpenMS ecosystem are use within quantms to store intermediat
 The easiest way to parse these files is to use `pyopenms <https://pyopenms.readthedocs.io/en/latest/>`_
 with its `pandas dataframe conversion capabilities <https://pyopenms.readthedocs.io/en/latest/user_guide/export_pandas_dataframe.html>`__.
 
+.. _tab-based-openms-formats:
+
+Tab-based OpenMS formats
+------------------------
+Several OpenMS tools also produce tab-separated files for tables of features, PSMs, and proteins.
+Refer to the OpenMS documentation for details and column descriptions.
+
 |Get help on Slack|   |Report Issue| |Get help on GitHub Forum|
 
-.. |Get help on Slack| image:: http://img.shields.io/badge/slack-nf--core%20%23quantms-4A154B?labelColor=000000&logo=slack
+.. |Get help on Slack| image:: https://img.shields.io/badge/slack-nf--core%20%23quantms-4A154B?labelColor=000000&logo=slack
                    :target: https://nfcore.slack.com/channels/quantms
 
 .. |Report Issue| image:: https://img.shields.io/github/issues/bigbio/quantms