Update and add general documentation

doc/source/index.rst

 Welcome to jackknife's documentation!
-=========================================
-
-.. TODO: note the modular nature of the code which allows to easily apply it to things other than
-   ADGA
+#####################################
 
 This code applies the method of jackknife resampling to abinito DGA calculations. Thus it allows to
 estimate e.g. the standard error of the mean or the covariance matrix of the DGA self-energy and
-susceptibilities.
+susceptibilities. However, due to the modular nature of the code it can easily be applied to other
+calculations.
 
 
-Installation:
--------------
+Installation
+============
 `jackknife` is written in Python 3 and requires the following packages:
 
    - NumPy (1.16.2)
@@ -32,11 +30,66 @@ quantities of ADGA.
 .. _w2dynamics: https://github.com/w2dynamics/w2dynamics
 
 
-Building documentation:
------------------------
-The documentation you are currently reading is built with Sphinx_. It uses Pyhton's docstrings and
-reStructuredText. To build it on your local machine you need to install Sphinx (e.g. with conda) 
-and execute the following commands::
+Usage
+=====
+The actual jackknife code is relatively easy to use, but one needs to generate quite a few input and
+config files with/for w2dynamics and ADGA beforehand.
+
+Input
+-----
+In order to estimate the standard error, covariance matrix, etc. of ADGA quantities the following
+input and config files are necessary:
+
+   - an ADGA config file
+   - a file containing the momentum resolved values of the tight-binding hamiltonian :math:`H(k)`
+   - a file containing the 1-particle Green's function from w2dynamics
+   - a file containing multiple 2-particle Green's functions from w2dynamics using worm sampling
+   - a jackknife config file
+
+For further details on the files regarding ADGA_ and w2dynamics_, see their respective
+documentation. An example for the jackknife configuration is provided in *example_config.ini*. So
+far there are three obligatory keys that every config file must contain:
+
+   - ``adga_root_directory``: the *ADGA* directory which contains the *scripts* and *bin* folder
+   - ``adga_config_file``: ususally *dga.conf*
+   - ``two_particle_file``: the file containing the 2-particle Green's functions from w2dynamics
+
+More control is possible with the following optional keys:
+
+   - ``output_file_prefix``: default value = "jackknife"; the current date and time will be appended
+     to this prefix for the output file
+   - ``store_output_samples``: default value = "no"; if set to "yes", the transformed bias-corrected
+     ouput samples will also be stored in the output file (see :class:`jackknife.Jackknife` for a
+     definition of those)
+   - ``calculate_self_energy``: default value = "yes"
+   - ``calculate_susceptibilities``: default value = "no"
+
+.. note::
+   It is not possible to calculate the self-energy and the susceptibilities at the same time. If
+   both options are set to "yes", only the self-energy will be calculated.
+
+Execution
+---------
+If all input and config files are available execute the following command to start the actual
+calculation::
+
+   python main.py [jackknife_config_file] [number_of_processes]
+
+If the number of processes is not specified, it is set to "1". If the name of the jackknife config
+file is not given, the default value *jackknife.ini* will be used.
+
+Output
+------
+For a list of all the statistical quantities that are written to the output file see e.g.:
+:meth:`jackknife.Jackknife.write_results_to_file()`. A description of the quantities can be found at
+:meth:`jackknife.Jackknife.do_estimation()`.
+
+
+Building the documentation
+==========================
+The documentation you are currently reading as well as all the source code documentation is built
+with Sphinx_. It uses Pyhton's docstrings and reStructuredText. To build it on your local machine
+you need to install Sphinx (e.g. with conda) and execute the following commands::
 
    cd .../jackknife/doc
    make html
@@ -46,14 +99,9 @@ The generated HTML files can be found in *.../jackknife/doc/build/html*. The mai
 
 .. _Sphinx: http://www.sphinx-doc.org/en/master/
 
-.. TODO: add the following stuff
-
-Usage/Tutorial:
-Code Documentation:
-
 
 List of modules
----------------
+===============
 .. toctree::
    :maxdepth: 2
 
@@ -61,11 +109,8 @@ List of modules
    jackknife
    adga
 
-.. TODO: add something like a getting started with installation, requirements, config description
-   and so on
-
 
 Indices
--------
+=======
 * :ref:`genindex`
 * :ref:`modindex`

example_config.ini

@@ -4,7 +4,7 @@
 adga_root_directory = /home/pkappl/programs/ADGA/
 adga_config_file = dga.conf
 two_particle_file = ../dmft/U4_b2_w2_n1e5-2019-07-02-Tue-14-55-45.hdf5
-; -----------------------
+; --- optional keys ---
 output_file_prefix = U4_b2_w2_n1e5_n4iwf20
 store_output_samples = no
 calculate_self_energy = yes

main.py

 #!/usr/bin/env python
 # TODO: Use Argparse for command line arguments and --help
-"""
-Usage:
-    python main.py [config file] [number of processes]
+# """
+# Usage:
+#     python main.py [config file] [number of processes]
 
-Everything after the second command line argument will be ignored. If
-the number of processes is not specified, the ADGA calculation will be
-done with a single process. If no config file is specified, the default
-value "jackknife.ini" will be used. For an example of such a config file
-see `example_config.ini`.
-"""
+# Everything after the second command line argument will be ignored. If
+# the number of processes is not specified, the ADGA calculation will be
+# done with a single process. If no config file is specified, the default
+# value "jackknife.ini" will be used. For an example of such a config file
+# see `example_config.ini`.
+# """
 
 import jackknife as jk
 import adga