diff --git a/README.md b/README.md
index 681f11e6019567708710d9f0471b26ea0a7ae5f0..5ffe8d3bba8706121decf1e7cf38a7683948d936 100644
--- a/README.md
+++ b/README.md
@@ -1 +1,11 @@
 # TFF2020 - Time-Frequency Fading
+
+Code and data to reproduce experiments from paper
+ *Time-frequency fading algorithms based on Gabor multipliers*
+ by A. Marina Krémé, Valentin Emiya, Caroline Chaux and Bruno Torré́sani, 2020.
+
+The sound material is available in folder 'data'.
+
+The code is available in folders 'matlab' and 'python'. The main experiments
+ are available in both programming languages. Some code is only available in
+  one language.  
\ No newline at end of file
diff --git a/python/README.rst b/python/README.rst
index 278b6445a51c504683b7b22577bf0b619552fd36..e82e6cac2cef2e9ebac746d84a7b372a63e07cf2 100755
--- a/python/README.rst
+++ b/python/README.rst
@@ -3,8 +3,9 @@ tffpy
 
 tffpy: a Python package for time-frequency fading using Gabor multipliers
 
-TODO: insert a general description here
-
+See paper
+ *Time-frequency fading algorithms based on Gabor multipliers*
+ by A. Marina Krémé, Valentin Emiya, Caroline Chaux and Bruno Torré́sani, 2020.
 
 Install
 -------
diff --git a/python/doc/index.rst b/python/doc/index.rst
index c86248168d43d31fa8f6ccffb9043863a4cf0f56..d5e4f4c196e9f639840366f3dc48952c2fcf1946 100755
--- a/python/doc/index.rst
+++ b/python/doc/index.rst
@@ -4,15 +4,23 @@
 
 Overview
 ========
-:mod:`tffpy`: time-frequency fading problem and solvers using Gabor
-multipliers, based on works by M. Kreme, V. Emiya, C. Chaux and B. Torrésani
-in 2020.
-
-The package :mod:`tffpy` includes:
-
-* TO
-* BE
-* COMPLETED
+:py:mod:`tffpy`: time-frequency fading problem and solvers using Gabor
+multipliers, based paper
+*Time-frequency fading algorithms based on Gabor multipliers*
+by M. Kreme, V. Emiya, C. Chaux and B. Torrésani in 2020.
+
+The package :py:mod:`tffpy` includes in particular:
+
+* class :py:class:`tffpy.tf_fading.GabMulTff` that implements the proposed
+  solver for reconstructing a source from a mixture and a time-frequency
+  binary mask.
+
+* class :py:class:`tffpy.experiments.exp_solve_tff.SolveTffExperiment` to
+  conduct the main experiment on mixtures of real sounds, with time-frequency
+  masks generated automatically, using the proposed solutions and baseline
+  solvers. Script `tffpy.scripts.script_exp_solve_tff` provide example of
+  code to handle the experiment (configuring, running on a computer grid or a
+  single computer, display results).
 
 Similar and complementary code is available in Matlab.
 
diff --git a/python/doc/references.rst b/python/doc/references.rst
index 63e19a56771f10450c3d6b8a905867e1da7b0aa1..da688d76c092d428efd354e0f19ce2b8f387cfad 100755
--- a/python/doc/references.rst
+++ b/python/doc/references.rst
@@ -4,10 +4,42 @@ References
     :Release: |release|
     :Date: |today|
 
-tffpy\.base module
-------------------
+tffpy\.create_subregions module
+-------------------------------
 
-.. automodule:: tffpy.base
+.. automodule:: tffpy.create_subregions
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+tffpy\.datasets module
+----------------------
+
+.. automodule:: tffpy.datasets
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+tffpy\.interpolation_solver module
+----------------------------------
+
+.. automodule:: tffpy.interpolation_solver
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+tffpy\.tf_fading module
+-----------------------
+
+.. automodule:: tffpy.tf_fading
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+tffpy\.tf_tools module
+----------------------
+
+.. automodule:: tffpy.tf_tools
     :members:
     :undoc-members:
     :show-inheritance:
@@ -19,3 +51,11 @@ tffpy\.utils module
     :members:
     :undoc-members:
     :show-inheritance:
+
+tffpy\.experiments\.exp_solve_tff module
+----------------------------------------
+
+.. automodule:: tffpy.experiments.exp_solve_tff
+    :members:
+    :undoc-members:
+    :show-inheritance: