Merge pull request #449 from cbielow/fixs

doc enhancements

Author: cbielow

docs/README.md

@@ -8,9 +8,16 @@ 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).
 
+    # create it:
     python -m venv /path/to/myenv
+    
     # activate it, e.g.
+    
+    # Linux:
     source <venv>/bin/activate
+    
+    # Windows:
+    c:\path\to\myenv\Scripts\activate.bat
 
 Once the environment is active, you can install all required python packages using
 

docs/source/community/build_from_source.rst

@@ -3,76 +3,14 @@ Build from Source
 
 To install pyOpenMS from :index:`source`, you will first have to compile OpenMS
 successfully on your platform of choice (note that for MS Windows you will need
-to match your compiler and Python version). Please follow the `official
-documentation
-<https://abibuilder.cs.uni-tuebingen.de/archive/openms/Documentation/release/latest/html/index.html>`_
-in order to compile OpenMS for your platform. Next you will need to install the
-following software packages
+to match your compiler and Python version). Please follow the 
+`official OpenMS documentation <https://openms.de/current_doxygen/>`_
+in order to compile OpenMS for your platform. 
 
-On Microsoft Windows: you need the 64 bit C++ compiler from Visual Studio 2015
-to compile the newest pyOpenMS for Python 3.5, 3.6 or 3.7. This is important,
-else you get a clib that is different than the one used for building the Python
-executable, and pyOpenMS will crash on import. The OpenMS wiki has `detailed information
-<https://github.com/OpenMS/OpenMS/wiki/Build-pyOpenMS-on-Windows>`_ 
-on building pyOpenMS on Windows.
-
-You can install all necessary Python packages on which pyOpenMS
-depends through
-
-.. code-block:: bash
-
-    pip install -U setuptools
-    pip install -U pip
-    pip install -U autowrap
-    pip install -U pytest
-    pip install -U numpy
-    pip install -U wheel
-
-Depending on your systems setup, it may make sense to do this inside a virtual environment
-
-.. code-block:: bash
-
-    virtualenv pyopenms_venv
-    source pyopenms_venv/bin/activate
-
-Next, we will configure the CMake-based OpenMS build system
-to enable the pyOpenMS target with the configuration option ``-DPYOPENMS=ON``.
-If your are using virtualenv or a specific Python version,
-add ``-DPYTHON_EXECUTABLE:FILEPATH=/path/to/python`` to ensure
-that the correct Python executable is used. Compiling pyOpenMS can use a lot of
-memory and take some time, however you can reduce the memory consumption by
-breaking up the compilation into multiple units and compiling in parallel, for
-example ``-DPY_NUM_THREADS=2 -DPY_NUM_MODULES=4`` will build 4 modules with 2
-threads. You can now configure pyOpenMS (inside your build folder) with:
-
-.. code-block:: bash
-
-    cmake -DPYOPENMS=ON
-    
-
-Remember, that you can pass the other options as described above to the first
-command by adding ``-DOPTION=VALUE`` statements if you need them.
-
-Now build pyOpenMS (now there should be pyOpenMS specific build targets).
-If you are still inside your build folder, you can use "." as the build
-folder parameter.
-
-.. code-block:: bash
-
-    cmake --build $YOURBUILDFOLDER --target pyopenms --config Release
-    
-
-Afterwards, test that all went well by running the tests:
-
-.. code-block:: bash
-
-    ctest -R pyopenms
-
-Which should execute all the tests and return with all tests passing.
+See https://github.com/OpenMS/OpenMS/tree/develop/src/pyOpenMS for installation instructions.
 
 Further Questions
 *****************
 
-In case the above instructions did not work, please refer to the `Wiki Page
-<https://github.com/OpenMS/OpenMS/wiki/pyOpenMS>`_, contact the development
-team on github or send an email to the OpenMS mailing list.
+In case the above instructions did not work, please contact the development
+team on GitHub (https://github.com/OpenMS/OpenMS/issues) or send an email to the OpenMS mailing list.

docs/source/user_guide/background.rst

@@ -221,10 +221,8 @@ Refer to the image below for a diagrammatic representation of the :term:`quadrup
 
 .. image:: img/introduction/quadrupole-analyzer.png
 
-.. raw:: html
+.. admonition:: Video
 
-    <div class="admonition video">
-    <p class="admonition-title">Video</p>
     For more information on :term:`quadrupole` analyzers, <a href="https://timms.uni-tuebingen.de:/tp/UT_20141028_002_cpm_0001?t=1477.00">view this video</a>.
     </div>
 

docs/source/user_guide/chemistry.rst

@@ -315,7 +315,7 @@ which produces
     Ethanol has 6 hydrogen atoms
 
 
-Note how in line 5 we were able to make a new molecule by adding existing
+Note how in line 3 we were able to make a new molecule by adding existing
 molecules (for example by adding two :py:class:`~.EmpiricalFormula` objects). In this
 case, we illustrated how to make ethanol by adding a :chem:`CH2` methyl group to an
 existing methanol molecule. Note that OpenMS describes sum formulas with the

docs/source/user_guide/digestion.rst

@@ -1,6 +1,21 @@
 Digestion
 =========
 
+In ``top-down proteomics``, whole proteins are measured in the mass spec.
+It is a hard problem to know the exact protein sequence, since proteins
+can be very large, i.e. have a very long sequence of constituing amino acids.
+
+However, in an orthogonal approach called ``bottom-up proteomics``,
+it is usually more beneficial to first cut proteins into smaller
+chunks at defined positions by using enzymatic digestion. The resulting peptides
+are lighter in mass, have less charge, and their sequence can be readily determined
+using MS/MS in many cases. In a subsequent step, one needs to infer which proteins
+were present in the sample, given a set of peptide sequences - a process called protein inference.
+The usual enzyme of choice for bottom-up proteomics is ``Trypsin`` (sometimes in combination with Lys-C).
+
+We will now learn how to do digestion of protein sequences in-silico, so you can predict which
+peptides you can expect to observe in the data and even generate theoretical spectra for them.
+
 Proteolytic Digestion with Trypsin
 **********************************
 
@@ -24,7 +39,7 @@ OpenMS has classes for proteolytic digestion which can be used as follows:
     print(result[4].toString())
     len(result)  # 82 peptides
 
-Very short peptides or even single amino acid digestion products are often discarded as they usually contain little information (e.g., can't be used to identify proteins).
+Very short peptides or even single amino acid digestion products are often discarded as they usually contain little information (e.g., are shared by many proteins making them useless to identify specific proteins or will not be detected in a real mass spectrum, since their peptide mass is below the usual minimal recorded mass).
 We now only generate digestion products with a length of :math:`7` to :math:`40`.
 
 .. code-block:: python
@@ -35,7 +50,7 @@ We now only generate digestion products with a length of :math:`7` to :math:`40`
     for s in result:
         print(s.toString())
 
-Enzymatic digestion is often not perfect and sometimes enzymes miss cutting a peptide.
+Enzymatic digestion is often not perfect and sometimes enzymes miss cutting position (aka cleavage site), resulting in some larger peptides. These are a sequence of two or even more consecutive peptides within the protein sequence.
 We now allow up to two missed cleavages.
 
 .. code-block:: python
@@ -51,6 +66,7 @@ We now allow up to two missed cleavages.
 Proteolytic Digestion with Lys-C
 ********************************
 
+In the previous example we used Trypsin as our enzyme of choice.
 We can of course also use different enzymes, these are defined in the ``Enzymes.xml``
 file and can be accessed using the :py:class:`~.EnzymesDB` object