Tutorial enhancements

.github/workflows/test-pr.yaml

@@ -1,60 +1,60 @@
-name: Build and Test code in notebooks
-
-on:
-  pull_request:
-    branches:
-      - master
-
-jobs:
-
-  build-test:
-    runs-on: ubuntu-latest
-
-    steps:
-    - uses: actions/checkout@v3
-
-    - uses: actions/setup-python@v4
-      with:
-        python-version: '3.10' # Version range or exact version of a Python version to use, using SemVer's version range syntax    
-
-    - name: Get changed files
-      id: changed-files
-      uses: tj-actions/changed-files@v41
-      with:
-          dir_names_max_depth: 0
-          files: |
-            docs/source/*.rst
-            docs/source/**/*.rst
-            !docs/source/**/_templates
-
-    - uses: r-lib/actions/setup-pandoc@v2
-      with:
-        pandoc-version: '3.1.2'
-
-#    - uses: actions/setup-python@v4
-#      with:
-#        python-version: '3.7' # Version range or exact version of a Python version to use, using SemVer's version range syntax
-
-    - name: Installing Dependencies
-      run: |
-        python3 -m pip install --upgrade pip
-        python3 -m pip install --upgrade pandocfilters jupyter
-        python3 -m pip install --upgrade -r requirements.txt
-
-
-    - name: Generating notebooks
-      run: |
-        pushd docs/source
-          ./generate_ipynb.sh
-        popd
-
-    - name: Execute all notebooks generated from modified files
-      run: |
-        for file in ${{ steps.changed-files.outputs.all_modified_files }}; do
-          jupyter nbconvert --to notebook --inplace --execute ${file%.rst}.ipynb || (echo "${file%.rst}" >> failed_nbs.txt)
-        done
-        if [ -f "failed_nbs.txt" ]; then
-          echo "Some notebooks failed to run. Please check logs."
-          cat failed_nbs.txt
-          exit 1
-        fi
+name: Build and Test code in notebooks
+
+on:
+  pull_request:
+    branches:
+      - master
+
+jobs:
+
+  build-test:
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v3
+
+    - uses: actions/setup-python@v4
+      with:
+        python-version: '3.10' # Version range or exact version of a Python version to use, using SemVer's version range syntax    
+
+    - name: Get changed files
+      id: changed-files
+      uses: tj-actions/changed-files@v45
+      with:
+          dir_names_max_depth: 0
+          files: |
+            docs/source/*.rst
+            docs/source/**/*.rst
+            !docs/source/**/_templates
+      
+    - uses: r-lib/actions/setup-pandoc@v2
+      with:
+        pandoc-version: '3.1.2'
+
+#    - uses: actions/setup-python@v4
+#      with:
+#        python-version: '3.7' # Version range or exact version of a Python version to use, using SemVer's version range syntax
+        
+    - name: Installing Dependencies
+      run: |
+        python3 -m pip install --upgrade pip
+        python3 -m pip install --upgrade pandocfilters jupyter
+        python3 -m pip install --upgrade -r requirements.txt
+
+    
+    - name: Generating notebooks
+      run: |
+        pushd docs/source
+          ./generate_ipynb.sh
+        popd
+
+    - name: Execute all notebooks generated from modified files
+      run: |
+        for file in ${{ steps.changed-files.outputs.all_changed_files }}; do
+          jupyter nbconvert --to notebook --inplace --execute ${file%.rst}.ipynb || (echo "${file%.rst}" >> failed_nbs.txt)
+        done
+        if [ -f "failed_nbs.txt" ]; then
+          echo "Some notebooks failed to run. Please check logs."
+          cat failed_nbs.txt
+          exit 1
+        fi

.gitignore

@@ -5,4 +5,5 @@ docs/source/_autosummary/*
 docs/source/apidocs/_autosummary/*
 docs/source/_build/
 docs/build/
-venv
+venv
+build/

docs/README.md

@@ -1,14 +1,31 @@
 pyOpenMS Documentation
 ======================
-
 The source code for the pyOpenMS documentation lies here. We use sphinx to
-build documentation and to build you can run 
+build documentation.
+
+Preparation
+
+Install Sphinx (which is a Python package) and some of its modules/plugins.
+We recommend doing this in a [python venv](https://docs.python.org/3/library/venv.html).
+
+    python -m venv /path/to/myenv
+    # activate it, e.g.
+    source <venv>/bin/activate
 
-    sphinx-build source/ build/
+Once the environment is active, you can install all required python packages using
 
-On a linux system, you can also use the provided Makefile and run 
+    cd <pyOpenMS_dir>/docs
+    pip install -r requirements.txt
+
+
+To build the docs run the line below (works on all operating systems), but make sure that your working dir is `<pyOpenMS_dir>/docs` (see above):
 
     make html
+
+and check validity of links using
+
+    make linkcheck
+
 
 
 

docs/make.bat

@@ -0,0 +1,37 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+if "%SPHINXOPTS%" == "" (
+  set SPHINXOPTS=-j auto
+)
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/requirements.txt

@@ -5,6 +5,9 @@ readthedocs-sphinx-search==0.3.2
 sphinx-copybutton==0.5.1
 sphinx-hoverxref
 sphinx-remove-toctrees
+## for pygment coloring of code snippets using ipython syntax
+ipython
+pygments-lexer-pseudocode
 
 --extra-index-url https://pypi.cs.uni-tuebingen.de/simple/
 pyopenms

docs/source/community/index.rst

@@ -15,8 +15,8 @@ displayed jupyter notebooks can not be used to edit the existing documentation.
 All edits need to happen through the .rst files in the OpenMS/pyopenms-docs repository.)
 
 If you are unsure how to do that or want to discuss questions 
-(e.g. your example workflow can be included on this webpage) contact us via the 
-`OpenMS Gitter chat channel <https://gitter.im/OpenMS/OpenMS/>`_.
+(e.g. your example workflow can be included on this webpage) contact the 
+`contact the OpenMS team <https://openms.de/communication/>`_ today.
 
 pyopenms sources
 ----------------

docs/source/community/wrapping_workflows_new_classes.rst

@@ -68,7 +68,7 @@ Open it and add your new function *with the correct indentation*:
   - Note: The space between the hash and wrap-doc (# wrap-doc) is not necessary, but used for consistency.
   - Note: Please start the comment with a capital letter.
 
-See the next section for a `simple example <#A-Simple-Example>`_ and a more `advanced example <#A-Further-Example>`_ of a wrapped class with several functions.
+See the next section for a `simple example <#a-simple-example>`_ and a more `advanced example <#a-further-example>`_ of a wrapped class with several functions.
 
 How to Wrap New Classes
 ^^^^^^^^^^^^^^^^^^^^^^^

docs/source/index.rst

@@ -1,13 +1,13 @@
 Summary
 =======
 
-pyOpenMS is an open-source Python library for :term:`mass spectrometry<Mass spectrometry>`, specifically for the analysis of proteomics
+pyOpenMS is an open-source Python library for :term:`mass spectrometry<Mass Spectrometry>`, specifically for the analysis of proteomics
 and metabolomics data in Python. pyOpenMS implements a set of Python bindings to the OpenMS library for computational
-:term:`mass spectrometry<Mass spectrometry>` and is available for Windows, Linux and macOS.
+:term:`mass spectrometry<Mass Spectrometry>` and is available for Windows, Linux and macOS.
 
 pyOpenMS provides functionality that is commonly used in computational mass
-spectrometry. The pyOpenMS package contains Python bindings for a large part of the `OpenMS <openms.de>`_
-library for :term:`mass spectrometry<Mass spectrometry>` based proteomics. It thus provides easy access to
+spectrometry. The pyOpenMS package contains Python bindings for a large part of the `OpenMS <https://openms.de>`_
+library for :term:`mass spectrometry<Mass Spectrometry>` based proteomics. It thus provides easy access to
 a feature-rich, open-source algorithm library for mass-spectrometry based proteomics analysis.
 
 pyOpenMS facilitates the execution of common tasks in proteomics (and other fields of mass spectrometry) such as
@@ -20,8 +20,8 @@ pyOpenMS facilitates the execution of common tasks in proteomics (and other fiel
 - Chromatogram analysis (chromatographic peak picking, smoothing, elution profiles and peak scoring for :term:`SRM`/MRM/PRM/:term:`SWATH`/DIA data)
 - Interaction with common tools in proteomics and metabolomics:
 
-  - Search engines such as Comet, Mascot, MSGF+, MSFragger, SpectraST, XTandem
-  - Post-processing tools such as Percolator, MSstats, Fido
+  - Search engines such as Comet, Mascot, MSGF+, MSFragger, SpectraST, Sage
+  - Post-processing tools such as Percolator, MSstats, Epiphany
   - Metabolomics tools such as SIRIUS, CSI:FingerId
 
 

docs/source/user_guide/adduct_detection.rst

@@ -16,7 +16,7 @@ In pyOpenMS, :py:class:`~.MetaboliteFeatureDeconvolution` takes a :term:`feature
 
 | **Suggested follow up step:**
 | The resulting feature map can be exported to a pandas DataFrame with adduct information from the *dc_charge_adducts* feature meta values.
-| Multiple feature maps can be `combined using the feature linking algorithms <feature_linking.html>`_. Each consensus feature will get a new meta value *best ion* based on the most common annotated adduct within the consensus feature group.
+| Multiple :term:`feature maps` can be `combined using the feature linking algorithms <feature_linking.html>`_. Each consensus feature will get a new meta value *best ion* based on the most common annotated adduct within the consensus feature group.
 
 .. code-block:: python
 

docs/source/user_guide/background.rst

@@ -17,14 +17,14 @@ Proteomics and metabolomics focus on complex interactions within biological syst
 
 Why use OpenMS
 ==============
-OpenMS is an open-source, C++ framework for analyzing large volumes of mass spectrometry data.
+OpenMS is an open-source, C++ framework hosted on `Github <https://github.com/OpenMS/OpenMS>` for analyzing large volumes of mass spectrometry data.
 It has been specially designed for analyzing high performance :term:`LC-MS` data but over recent times,
 has been extended to analyze data generated by other techniques.
 
 .. note::
 
     OpenMS in recent times has been expanded to support a wide variety of mass spectrometry experiments.
-    To design your analysis solution, `contact the OpenMS team <https://openms.github.io/community/>`_ today.
+    To design your analysis solution, `contact the OpenMS team <https://openms.de/communication/>`_ today.
 
 To use OpenMS effectively, an understanding of :term:`liquid chromatography` (:term:`LC`) and
 mass spectrometry (MS) is required as many of the algorithms are based on these techniques. This