Merge staging branch in test branch

.github/CONTRIBUTING.md

@@ -5,14 +5,14 @@ Hi there!
 
 Thank you for thinking about enhancing OpenMS Documentation further.
 
-Please feel free:
+Please feel free to:
 
-1. Creating a bug report or feature request in OpenMS Documentation, [here](https://github.com/OpenMS/OpenMS-docs/issues).
-2. Creating a pull request in [OpenMS Documentation](https://github.com/OpenMS/OpenMS-docs) with the change you're proposing.
+1. Create a bug report or feature request in OpenMS Documentation, [here](https://github.com/OpenMS/OpenMS-docs/issues).
+2. Create a pull request in [OpenMS Documentation](https://github.com/OpenMS/OpenMS-docs) with the change you're proposing.
 
-If you need help while doing any of these, drop us a ping in [OpenMS Gitter](https://gitter.im/OpenMS/OpenMS).
+For any questions, drop us a ping in [OpenMS Gitter](https://gitter.im/OpenMS/OpenMS).
 
-## Creating a Pull Request
+## Create a Pull Request(PR)
 
 1. Fork this repository.
 2. Add the change in your fork.
@@ -27,7 +27,22 @@ If you need help while doing any of these, drop us a ping in [OpenMS Gitter](htt
 2. Restrict the line length to 120 characters, including space(s).
 3. Title and H1 heading should be in `Title Case`. Follow `Sentence case`, until otherwise stated.
 4. Write as OpenMS is writing for itself as an object and subject.
-5. Be nice, polite, and respectful.
+5. Use American English.
+6. Use `backtick`(s) for formatting code, library name, files, and path.
+7. Use **bold** for product name, object name, an independent entity.
+8. Use **bold** for menu title in an application.
+9. Link to glossary terms using {term}`this is a glossary term`.
+10. OpenMS documentation uses following Admonitions
+    - Hint
+	- Important
+	- Note
+	- Warning
+	- Tip
+	- See Also
+	Example of these are present in documentation, please follow them.
+11. Always specify lexers for code blocks.
+12. Format keyboard strokes using `<kbd>qwerty-keyboard-button</kbd>`.
+13. Be nice, polite, and respectful.
 
 ### Naming files
 
@@ -36,13 +51,13 @@ If you need help while doing any of these, drop us a ping in [OpenMS Gitter](htt
 
 ### Images and figures
 
-For images and figures, follow:
+For images and figures:
 
-1. Add screenshot of the window.
+1. Add a screenshot of the window.
 2. In tutorial, align images in center. Other instructions, should have alighment to left.
 3. Please set the size to `500px` of images added in step-by-step guides or instructions.
 
-## OpenMS Documentation Contributors
+## OpenMS documentation contributors
 
 Thank you for your contribution!
 

.github/ISSUE_TEMPLATE/feature-request.md

@@ -13,14 +13,14 @@ Thanks for suggesting a new feature for the OpenMS Documentation!
 Please delete this text and anything that's not relevant from the template below:
 -->
 
-## Is your feature request related to a OpenMS Documentation problem? Please describe 
+## Is your feature request related to a OpenMS API Reference Documentation? Please describe.
 
-<!-- 
+<!--
 
 For feature request in OpenMS, please create issue in [OpenMS](https://github.com/OpenMS/OpenMS/issues)
-Please provide a clear and concise description of what the problem is in documentation. 
+Please provide a clear and concise description of what the problem is in documentation.
 -->
-- [ ] I have attached screenshot describing the problem, if applicable
+- [ ] I have attached screenshot describing the problem, if applicable.
 
 ## Describe the documentation enhancement you'd like
 

conf.py

@@ -76,9 +76,9 @@
 html_theme = 'furo'
 html_logo = 'assets/OpenMS_transparent_background.png'
 
-pygments_style = "sphinx"
-pygments_dark_style = "monokai"
+pygments_style = 'sas'
 
+pygments_dark_style = 'rrt'
 
 
 # Add any paths that contain custom static files (such as style sheets) here,

docs/additional-resources/developer-guidelines-for-addding-new-dependent-libraries.md

@@ -0,0 +1,68 @@
+Developer Guidelines For Adding New Dependent Libraries
+======================================================
+
+# Our dependency library philosophy
+
+In short, requirements for adding a new library are:
+- indispensable functionality
+- license compatibility
+- availability for all platforms
+
+## Indispensable functionality
+
+In general, adding a new dependency library (of which we currently have more than a handful, e.g. Xerces-C or ZLib)
+imposes a significant integration and maintenance effort. Thus, the new library should add **indispensable functionality**.
+If the added value does not compensate for the overhead, alternative solutions encompass:
+
+- write it yourself and add to the OpenMS library (i.e. its repository) directly
+- write a TOPPAdapter which calls an external executable (placing the burden on the user to supply the executable)
+
+## License compatibility
+
+OpenMS has a BSD-3 clause license and we try hard to remove dependencies of GSL-like libraries. Therefore, a new library
+with e.g. LGPL-2 would be prohibitive.
+
+
+## C++ standard compatibility
+
+Needs to be compatible and therefore compilable with the same C++ standard as OpenMS.
+
+## Availability for all platforms
+
+OpenMS is meant to run and behave the same on the three main operating systems, i.e., Windows, macOS and Linux. Adding
+a new dependent library is thus required to be available on these platforms
+
+- on **WindowsOS** this usually means, adding the new library to the Contrib in debug and release variants. In short all
+  recent versions of Visual Studio (VS2008 and onwards) must be supported (or support must be added). This encompasses
+  - a solution file (which can be either statically present or generated by a meta-system like CMake) is available
+  - the lib actually compiles and is linked to the **dynamic** VS-C++ runtime lib (since this is what the OpenMS lib will
+  link to as well - combining static and dynamic links will lead to linker errors or segfaults).
+
+- on **macOS** it should be ensured that the library can be build on recent macOS versions (> 10.10) compiled using the
+  mac specific _libc++_. Ideally the package should be available via **HomeBrew** or **MacPorts** so we can directly use
+  those libraries instead of shipping them via the contrib. Additionally, the MacPorts and HomeBrew formulas for building
+  the libraries can serve as blueprints on how to compile the library in a generic setting inside the contrib which should
+  also be present.
+
+- on **Linux** since we (among other distributions) feature an OpenMS Debian package which requires that all dependencies
+  of OpenMS are available as Debian package as well, the new library must be available (or made available) as Debian
+  package or linked statically during the OpenMS packaging build.
+
+## How to add it to the contrib build
+
+Add a CMake file to `OpenMS/contrib` into the `libraries.cmake` folder on how to build the library. Preferably of course
+the library supports building with CMake (see Xerces) which makes the script really easy. It should support static and
+dynamic builds on every platform. Add the compile flag for position independent code (e.g. `-fpic`) in the static version.
+Add patches in the *patches* folder and call them with the macros in the `macros.cmake` file. Create patches with
+`diff -Naur original_file my_file > patch.txt`. If there are problems during applying a patch, make sure to double check
+filepaths in the head of the patch and the call of the patching macro in CMake.
+
+- All the libraries need to go into (e.g. copied/installed/moved) to `$buildfolder/lib`
+- All the headers under `$buildfolder/include/$libraryname` (the only exception to leave out the library name subfolder
+  is when the `Find$libraryname.cmake` does not support this subfolder e.g. because system libraries are not structured
+  like this, see boost).
+- All needed files into `$buildfolder/share/$libraryname`
+
+Then test the build on your platform including a subsequent build of OpenMS using that library. Submit a pull request to
+`OpenMS/contrib`. Submit a pull request to `OpenMS/OpenMS` that updates the contrib submodule. Make sure the libraries
+are correctly shipped in pyOpenMS and the packages (especially dynamic libraries and especially on Windows).

docs/additional-resources/external-code-using-openms.md

@@ -0,0 +1,120 @@
+External Code using OpenMS
+==========================
+
+If OpenMS' TOPP and UTILS tools are not enough in a certain scenario, you can either request a change to OpenMS, if you
+feel this functionality is useful for others as well, or modify/extend OpenMS privately. For the latter, there are multiple
+ways to do this:
+
+- Modify the developer version of OpenMS by changing existing tools or adding new ones.
+- Use an **External Project** to write a new tool, while not touching OpenMS itself (see below on how to do that).
+
+Once you've finished your new tool, and it only needs to run on the development machine. To ship it to a new client machine,
+see, read further in this document.
+
+# Compiling external code
+
+It is very easy to set up an environment to write your own programs using OpenMS. Make sure to downloaded and installed
+the source package of OpenMS/TOPP properly.
+
+```{note}
+You cannot use the `install` target when working with the development version of OpenMS, it must be built and used within
+the build tree.
+```
+
+All important compiler settings and preprocessor definitions along with the OpenMS library are available. The most
+important variables are:
+
+- `OpenMS_INCLUDE_DIRECTORIES`:  all include directories containing OpenMS headers
+- `OPENMS_ADDCXX_FLAGS`: preprocessor macros we require written as `(-DMACRO1 -DMACRO2)`
+
+and the OpenMS target itself (which you can link against).
+
+The example that follows will be explained in details:
+
+```cpp
+### example CMakeLists.txt to develop C++ programs using OpenMS
+project("Example_Project_using_OpenMS")
+cmake_minimum_required(VERSION 3.0)
+
+## list all your executables here (a corresponding .cpp file should exist, e.g. Main.cpp)
+set(my_executables
+  Main
+)
+
+## list all classes here, which are required by your executables
+## (all these classes will be linked into a library)
+set(my_sources
+  ExampleLibraryFile.cpp
+)
+
+## find OpenMS configuration and register target "OpenMS" (our library)
+find_package(OpenMS)
+## if the above fails you can try calling cmake with -D OpenMS_DIR=/path/to/OpenMS/
+## or modify the find_package() call accordingly
+## find_package(OpenMS PATHS "</path/to/OpenMS//")
+
+# check whether the OpenMS package was found
+if (OpenMS_FOUND)
+  message(STATUS "\nFound OpenMS at ${OpenMS_DIR}\n")
+
+  ## library with additional classes from above
+  add_library(my_custom_lib STATIC ${my_sources})
+
+  ## add targets for the executables
+  foreach(i ${my_executables})
+    add_executable(${i} ${i}.cpp)
+    ## link executables against OpenMS
+    target_link_libraries(${i} OpenMS my_custom_lib)
+  endforeach(i)
+
+
+else(OpenMS_FOUND)
+  message(FATAL_ERROR "OpenMSConfig.cmake file not found!")
+endif(OpenMS_FOUND)
+```
+
+The command `project` defines the name of the project, the name is only of interest of you're working in an IDE or want
+to export this project's targets. To compile the program, append it to the `my_executables` list. If you use object files
+(classes which do not contain a main program), append them to the `my_sources` list. In the next step CMake creates a
+statically linked library of the object files, listed in `my_sources`. This simple CMakeLists.txt example can be
+extended to also build shared libraries, include other external libraries and so on.
+
+An example external project can be found in `OpenMS/share/OpenMS/examples/external_code`. Copy these files to a separate
+directory and use CMake to configure it (here as an in-source build).
+
+```bash
+cd <path_to_external_project>
+cmake -G "<generator>" .
+```
+
+For more information visit the website of cmake at cmake.org and consult the documentation.
+
+```{important}
+Have fun coding with OpenMS!
+```
+
+# Shipping external code to a new machine
+
+If you've modified OpenMS itself and not used an external project use our installer scripts, to build your own OpenMS
+installer for your platform (see our internal FAQ which is built using "make doc_internal") and ship that to a client
+machine.
+
+If you've used an external project and have a new executable (+ an optional new library), use the installer approach as
+well, and manually copy the new executable to the `TOPP/UTILS` binary directory (e.g. on Windows this could be
+`c:/program files/OpenMS/bin`, on Linux it could be `/bin`.
+
+If you do NOT use the installer, copy all required files manually, plus a few extra steps, see below. What needs to be
+done is a little platform dependent, thus very cumbersome to explain. Look at the cmake installer scripts, to see whats
+required (for Mac and Linux see `OpenMS/cmake/package*.cmake`).
+
+In short:
+
+- copy the `OpenMS/share/OpenMS` directory to the client machine (e.g `<client/my_dir>/share`) and set the environment
+  variable `OPENMS_DATA_PATH` to this directory
+- copy the OpenMS library (`OpenMS.dll` for Windows or `OpenMS.so/.dylib` for Linux/Mac) to `<client/my_dir>/bin`.
+- copy all Qt4 libraries to the client `<client/my_dir>/bin` or on Linux/Mac make sure you have installed the Qt4 package
+- [Windows only] copy Xerces dll (see `contrib/lib`) to `<client/my_dir>/bin`
+- [Windows only] install the VS redistributable package (see Microsoft Homepage) on the client machine which corresponds
+  to the VS version that was used to compile your code (use the correct redistributable package!, i.e., architecture
+  32|64bit, VS version, VS Service Pack version). If you choose the wrong redistributable package, you will get
+  "Application failed to initialize properly..." error messages.