Restructure and Rearrange OpenMS RTD Documentation

conf.py

@@ -78,6 +78,8 @@
 #
 html_theme = 'furo'
 html_logo = 'assets/logo/OpenMS_transparent_background.png'
+html_favicon = 'assets/logo/OpenMS_transparent_background.png'
+
 html_theme_options = {
     "navigation_with_keys": True,
     "light_css_variables": {
@@ -90,7 +92,6 @@
 
 pygments_dark_style = 'rrt'
 
-
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".

docs/contribute-to-openms/adding-new-tool-to-topp.md

@@ -0,0 +1,100 @@
+Adding New Tool to The TOPP suite
+=====================================
+
+## The OpenMS pipeline (TOPP)
+
+Any tool that is written with the OpenMS library can easily be made into a TOPP tool by simply using the OpenMS command
+line parser which is able to parse ParamXML, a powerful XML based description of the tool. Hence most analysis algorithms
+in OpenMS are available as a stand-alone tool which can be called on the command line or integrated into workflow engines
+via the CTD mechanism. A current list of TOPP tools can be found in [the documentation](https://abibuilder.informatik.uni-tuebingen.de/archive/openms/Documentation/release/latest/html/TOPP_documentation.html).
+
+## What do I have to do to add a new TOPP tool?
+
+The recommended way is to inherit from the class TOPPBase as in existing TOPP tools (sources available in /src/topp/). This will add command line parsing functionality to your tool as described in the TOPP section of this page.
+
+- Add the code to `src/topp/` and register it in `src/topp/executables.cmake`
+- Add your tool (with the correct category) to `getTOPPToolList()` in `src/openms/source/APPLICATIONS/ToolHandler.cpp`.
+  This creates a doxygen page with the `–help` output of the tool (using `TOPPDocumenter`). This page must be included
+  at the end of the doxygen documentation of your tool (see other tools for an example).
+- Add it to the TOPP docu page (in `doc/doxygen/public/TOPP.doxygen`)
+- Add the name to `src/topp/executables.cmake`
+- Write a TOPP test (add it to `src/tests/topp/CMakeLists.txt`)
+
+```{warning}
+Handle any kind of input files to your TOPP tool via command line flags and use the `${DATA_DIR_TOPP}` prefix. Use
+ini-files to specify output-files, but not input-files. Doing otherwise will break out-of-source builds.
+```
+
+```{hint}
+add `-test` to the call of your TOPP tool and also create the expected output that you put in `src/tests/topp` with that
+flag active. The flag ensures that UniqueId's,  dates etc are equal no matter where and when the tool is run.
+```
+
+## What do I have to do to add a new UTILS tool?
+
+- Add the code to `src/utils/` and register it in `src/utils/executables.cmake`.
+- Add your tool to `getUtilList()` in `src/openms/source/APPLICATIONS/ToolHandler.cpp`. This creates a doxygen page with
+  the `–help` output of the tool (using `TOPPDocumenter`). This page must be included at the end of the doxygen
+  documentation of your tool (see other tools for an example).
+- Add it to the UTILS docu page (in `doc/doxygen/public/UTILS.doxygen`)
+- Write a test (this is optional for UTILS). See TOPP tools above and add the test to the bottom of `src/tests/topp/CMakeLists.txt`.
+
+## I want to implement a new file adapter. What is to be done?
+
+First, add a file adapter class to the `include/OpenMS/FORMAT/` and `source/FORMAT/` folders. The file adapter should
+implement a default constructor, a load method and a store method. Make sure your code conforms to the OpenMS Coding
+conventions. For automatic file type recognition, you need to
+
+- register your new file type at the Type enum in `/include/OpenMS/FORMAT/FileTypes.h`,
+- flag the file type as supported in the isSupported method of `/source/FORMAT/FileHandler.C`
+- register the file extension in the getTypeByFileName method of `/source/FORMAT/FileHandler.C`
+
+If the new file is a peak or feature file format you should also add it to loadExperiment or loadFeatures, respectively,
+of the FileHandler class. To add the file format to the TOPPView open dialog, you have to modify the file
+`/source/APPLICATIONS/TOPPViewBase.C`.
+
+- Add the file extensions to the filter_all and filter_single variables of the getFileList_ method.
+
+To add your format to TOPP applications:
+
+- add the file extension to the extensions list of the respective parameter:
+  ```
+  e.g. setValidStrings_("in_type", StringList::create("mzData,mzXML,mzML")); in FileInfo
+  ```
+
+## How to create an icon file for a TOPP tool under Windows?
+
+- Create an .ico file: first, you need some graphics program (The GIMP is recommended) think of a motive and remind
+  yourself that you have limited space. Create at least a 16x16, 32x32, 48x48 and 64x64 pixel version and save each of
+  them in a separate layer of the respective size. Do not add any larger sized layers, since Win XP will not display any
+  icon then. When saving the image as type `.ico` the GIMP will ask you for the color depth of each layer. As it is
+  recommended to have multiple color depths of each icon-size, go back to the layers and duplicate each layer twice.
+  That should give you 12 layers. Now, save the image as `.ico` (e.g. TOPPView.ico) file, giving each group of equal
+  sized layers a 32 bit (8 bit transparency), 8 bit (1 bit transparency), 4 bit (1 bit transparency) color depth.
+
+```{attention}
+Make sure to assign the higher color depth to the upper layers as Windows will not pick the highest possible color
+otherwise.
+```
+
+- Create a resource file: Create a text file named `.rc` (e.g. TOPPView.rc) Insert the following line: 101 ICON
+  "TOPPView.ico" , replacing TOPPView with your binary name. Put both files in `OpenMS/source/APPLICATIONS/TOPP/`
+  (similar files for other TOPP tools already present). Re-run cmake and re-link your TOPP tool. 
+
+Voila. You should have an iconized TOPP tool.
+
+## Develop your Tool in an external project using OpenMS
+
+To include the OpenMS library in one of your projects, we recommend to have a look at a small emulated external project
+in our repository. We strongly suggest to use CMake for building your project together with OpenMS to  make use of the
+macros and environment information generated during the build of the OpenMS library.
+
+## The Common Tool Description (CTD)
+
+The CTD is a format developed from the OpenMS team to allow the user to use TOPP tools also in other workflow engines.
+Each tool can output a CTD description of itself (the XML scheme for the CTD can be found here), which can then be used
+by a node generator program to generate nodes for different workflow engines. The CTD mechanism is shared by OpenMS with
+other mature libraries like SeqAn and BALL. An example for a node generation program are the Generic KNIME Nodes. The
+most complete description on how to generate your own Generic KNIME Nodes based on a CTD (e.g. from your freshly
+developed command line tool), can be found on the SeqAn documentation. We are working on a tutorial specifically
+tailored to OpenMS.

docs/contribute-to-openms/advanced.md

@@ -0,0 +1,10 @@
+Advanced
+========
+```{toctree}
+:maxdepth: 1
+
+advanced/developer-guidelines-for-adding-new-dependent-libraries.md
+advanced/build-custom-knime-plugin.md
+advanced/custom-compilation.md
+
+```

docs/develop-with-openms/api-reference.md

@@ -0,0 +1,2 @@
+API Reference
+=============

docs/develop-with-openms/build-openms-from-source.md

@@ -0,0 +1,2 @@
+Build OpenMS from Source
+========================

docs/develop-with-openms/developer-tutorial.md

@@ -0,0 +1,2 @@
+Developer Tutorial
+==================

docs/develop-with-openms/openms-core-library.md

@@ -0,0 +1,2 @@
+OpenMS C++ Core Library
+=======================

docs/develop-with-openms/pyopenms.md

@@ -0,0 +1,2 @@
+pyOpenMS
+========

docs/graphical-topp-tools/ini-file-editor.md

@@ -0,0 +1,10 @@
+INIFileEditor
+============
+
+Can be used to visually edit INI files of TOPP tools.
+
+The values can be edited by double-clicking or pressing <kbd>F2</kbd>.
+
+The documentation of each value is shown in the text area on the bottom of the widget.
+
+![INIFileEditor](../images/topp/INIFileEditor.png)

docs/graphical-topp-tools/swathwizard.md

@@ -0,0 +1,24 @@
+SwathWizard
+==========
+
+An assistant for Swath analysis.
+
+The Wizard takes the user through the whole analysis pipeline for SWATH proteomics data analysis, i.e. the
+[TOPP Documentation: OpenSwathWorkflow](https://abibuilder.informatik.uni-tuebingen.de/archive/openms/Documentation/nightly/html/UTILS_OpenSwathWorkflow.html) tool, including downstream tools such as [GitHub:PyProphet/pyProphet](https://github.com/PyProphet/pyprophet) and the [GitHub:msproteomicstools/TRIC alignment](https://github.com/msproteomicstools/msproteomicstools) tool.
+
+Since the downstream tools require Python and the respective modules, the Wizard will check their proper installation
+status and warn the user if a component is missing.
+
+Users can enter the required input data (mzML MS/MS data, configuration files) in dedicated fields, usually by drag and
+droping files from the operating systems' file explorer (Explorer, Nautilus, Finder...). The output of the Wizard is
+both the intermediate files from OpenSWATH (e.g. the XIC data in `.sqMass` format) and the tab-separated table format
+(`.tsv`) from pyProphet and TRIC.
+
+This is how the wizard looks like:
+
+![SwathWizard](../images/topp/SwathWizard.png)
+
+A schematic of the internal data flow (all tools are called by SwathWizard in the background) can be found in the
+[TOPP Documentation: SwathWizard](https://abibuilder.informatik.uni-tuebingen.de/archive/openms/Documentation/nightly/html/TOPP_SwathWizard.html).
+
+A recommended test data for the Wizard is the [PASS00779](https://db.systemsbiology.net/sbeams/cgi/PeptideAtlas/PASS_View?identifier=PASS00779) dataset.

docs/graphical-topp-tools/topp.md

@@ -0,0 +1,22 @@
+TOPP
+===
+
+**TOPP - The OpenMS Proteomics Pipeline** is a pipeline for the analysis of HPLC-MS data. It consists of several small
+applications that can be chained to create analysis pipelines tailored for a specific problem.
+
+The TOPP tools are divided into several subgroups, like graphical tools, file handling, signal processing and
+preprocessing, quantitation, map alignment, protein/peptide identification, protein/peptide processing, targeted
+experiments and OpenSWATH, peptide property prediction, cross-linking, quality-control, among a few.
+
+Few of the graphical tools are explained below:
+
+```{toctree}
+:maxdepth: 1
+
+toppview
+toppas
+ini-file-editor
+swathwizard
+```
+
+For advanced documentation on every TOPP tool, see the [OpenMS TOPP API Reference](https://abibuilder.informatik.uni-tuebingen.de/archive/openms/Documentation/nightly/html/TOPP_documentation.html).

docs/graphical-topp-tools/toppas.md

@@ -0,0 +1,30 @@
+TOPPAS
+======
+
+An assistant for GUI-driven TOPP workflow design.
+
+**TOPPAS** allows to create, edit, open, save, and run TOPP workflows. Pipelines can be created conveniently in a GUI by
+means of mouse interactions. The parameters of all involved tools can be edited within the application and are also
+saved as part of the pipeline definition in the `.toppas` file. Furthermore, TOPPAS interactively performs validity
+checks during the pipeline editing process, in order to make it more difficult to create an invalid workflow. Once set
+up and saved, a workflow can also be run without the GUI using the `ExecutePipeline` TOPP tool.
+
+The following figure shows a simple example pipeline that has just been created and executed successfully:
+
+![TOPPAS simple example](../images/topp/TOPPAS_simple_example.png)
+
+More information about TOPPAS can be found in the [TOPPAS tutorial](../tutorials/TOPP/TOPPAS-tutorial.md).
+
+**The command line parameters of this tool are**:
+
+```bash
+TOPPAS -- An assistant for GUI-driven TOPP workflow design.
+
+Usage:
+ TOPPAS [options] [files]
+
+Options are:
+  --help           Shows this help
+  --debug          Enables debug messages
+  -ini <File>      Sets the INI file (default: ~/.TOPPAS.ini)
+```

docs/graphical-topp-tools/toppview.md

@@ -0,0 +1,34 @@
+TOPPView
+=======
+
+**TOPPView** is a viewer for MS and HPLC-MS data. It can be used to inspect files in mzML, mzData, mzXML and several other
+file formats. It also supports viewing data from an OpenMS database. The following figure shows two instances of TOPPView
+displaying a HPLC-MS map and a MS raw spectrum:
+
+![TOPPView](../images/topp/TOPPView.png)
+
+More information about TOPPView can be found in the [TOPP tutorial](../tutorials/TOPP/TOPP-tutorial.md).
+
+**The command line parameters of this tool are**:
+
+```bash
+TOPPView -- A viewer for mass spectrometry data.
+
+Usage:
+ TOPPView [options] [files]
+
+Options are:
+  --help           Shows this help
+  -ini <File>      Sets the INI file (default: ~/.TOPPView.ini)
+  --force          Forces scan for new tools/utils
+
+Hints:
+ - To open several files in one window put a '+' in between the files.
+ - '@bw' after a map file displays the dots in a white to black gradient.
+ - '@bg' after a map file displays the dots in a grey to black gradient.
+ - '@b'  after a map file displays the dots in black.
+ - '@r'  after a map file displays the dots in red.
+ - '@g'  after a map file displays the dots in green.
+ - '@m'  after a map file displays the dots in magenta.
+ - Example: 'TOPPView 1.mzML + 2.mzML @bw + 3.mzML @bg'
+```