Docs: More documentation on input files and rescoring engine configur…

…ation.

docs/source/userguide/configuration.rst

@@ -271,6 +271,35 @@ the following configuration can be used:
     max_psm_rank_output = 1
 
 
+Configuring rescoring engines
+=============================
+
+MS²Rescore supports multiple rescoring engines, such as Mokapot and Percolator. The rescoring
+engine can be selected and configured with the ``rescoring_engine`` option. For example, to use
+Mokapot with a custom train_fdr of 0.1%, the following configuration can be used:
+
+.. tab:: JSON
+
+  .. code-block:: json
+
+    "rescoring_engine": {
+      "mokapot": {
+        "train_fdr": 0.001
+      }
+
+.. tab:: TOML
+
+    .. code-block:: toml
+
+      [ms2rescore.rescoring_engine.mokapot]
+      train_fdr = 0.001
+
+
+All options for the rescoring engines can be found in the :ref:`ms2rescore.rescoring_engines`
+section.
+
+
+
 All configuration options
 =========================
 

docs/source/userguide/input-files.rst

@@ -5,23 +5,31 @@ Input files
 PSM file(s)
 ===========
 
-The peptide-spectrum match (PSM) file is generally the output from a proteomics search engine.
-This file serves as the main input to MS²Rescore. One or multiple PSM files can be provided at
-once. Note that merging PSMs from different MS runs could have an impact on the correctness of
-the FDR control.
+The **peptide-spectrum match (PSM) file** is generally the output from a proteomics search engine.
+This file serves as the main input to MS²Rescore.
 
-Various PSM file types are supported. The type can be specified with the ``psm_file_type`` option.
-Check the list of :py:mod:`psm_utils` tags in the
-:external+psm_utils:ref:`supported file formats <supported file formats>` section. Depending on the
-file extension, the file type can also be inferred from the file name. In that case,
-``psm_file_type`` option can be set to ``infer``.
+The PSM file should contain **all putative identifications** made by the search engine, including
+both target and decoy PSMs. Ensure that the search engine was configured to include decoy entries
+in the search database and was operated with **target-decoy competition** enabled (i.e.,
+considering both target and decoy sequences simultaneously during the search).
 
 .. attention::
    As a general rule, MS²Rescore always needs access to **all target and decoy PSMs, without any
    FDR-filtering**. For some search engines, this means that the FDR-filter should be disabled or
    set to 100%.
 
 
+One or multiple PSM files can be provided at once. Note that merging PSMs from different MS runs
+could have an impact on the correctness of the FDR control. Combining multiple PSM files should
+generally only be done for LC-fractionated mass spectrometry runs.
+
+Various PSM file types are supported. The type can be specified with the ``psm_file_type`` option.
+Check the list of :py:mod:`psm_utils` tags in the
+:external+psm_utils:ref:`supported file formats <supported file formats>` section. Depending on the
+file extension, the file type can also be inferred from the file name. In that case,
+``psm_file_type`` option can be set to ``infer``.
+
+
 Spectrum file(s)
 ================
 

docs/source/userguide/output-files.rst

@@ -52,8 +52,8 @@ Rescoring engine files:
 | ``<prefix>.<mokapot/percolator>.weights.txt``               | Feature weights, showing feature usage in the rescoring run |
 +-------------------------------------------------------------+-------------------------------------------------------------+
 
-If no rescoring engine is selected (or if Percolator was selected), the following files will also
-be written:
+If no rescoring engine is selected, if Percolator was selected, or in DEBUG mode, the following
+files will also be written:
 
 +-------------------------------------------------------------+-----------------------------------------------------------+
 | File                                                        | Description                                               |