diff --git a/docs/src/modules.rst b/docs/api.rst
similarity index 55%
rename from docs/src/modules.rst
rename to docs/api.rst
index bcb5083..a089602 100644
--- a/docs/src/modules.rst
+++ b/docs/api.rst
@@ -1,8 +1,8 @@
-bumblebee-status
+API Reference
 ================
 
 .. toctree::
    :maxdepth: 4
 
-   core
-   util
+   src/core
+   src/util
diff --git a/docs/development/index.rst b/docs/development/index.rst
index beea50c..3fc86fc 100644
--- a/docs/development/index.rst
+++ b/docs/development/index.rst
@@ -8,9 +8,3 @@ Developer's Guide
    module
    theme
 
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
diff --git a/docs/docstring.tmpl b/docs/docstring.tmpl
new file mode 100644
index 0000000..9dc7dec
--- /dev/null
+++ b/docs/docstring.tmpl
@@ -0,0 +1,9 @@
+    """<desc>
+
+    :param <name>: <desc> 
+
+    :raises <error>: <desc>
+
+    :return: <desc>
+    :rtype: <type>
+	"""
diff --git a/docs/index.rst b/docs/index.rst
index d430a75..428ee86 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -6,6 +6,43 @@
 Welcome to bumblebee-status's documentation!
 ============================================
 
+bumblebee-status is a modular, theme-able status line generator for the
+`i3 window manager <https://i3wm.org/>`__.
+
+Focus is on:
+
+ - ease of use, sane defaults (no mandatory configuration file)
+ - custom modules: :doc:`development/module`
+ - custom themes: :doc:`development/theme`
+ 
+I hope you like it and I appreciate any kind of feedback: bug reports,
+feature requests, etc. :)
+
+Thanks a lot!
+
++------------------------------------+-------------------------+
+| **Required i3wm version**          | 4.12+                   |
++------------------------------------+-------------------------+
+| **Supported Python versions**      | 3.4, 3.5, 3.6, 3.7, 3.8 |
++------------------------------------+-------------------------+
+| **Supported FontAwesome versions** | 4 only                  |
++------------------------------------+-------------------------+
+| **Per-module requirements**        | see :doc:`modules`      |
++------------------------------------+-------------------------+
+
+see :doc:`FAQ` for details on this
+
+Example usage:
+
+.. code-block::
+
+   bar {
+       status_command <path>/bumblebee-status \
+        -m cpu memory battery time pasink pasource \
+        -p time.format="%H:%M" \
+        -t solarized
+   }
+
 .. toctree::
    :maxdepth: 2
    :caption: Contents
@@ -17,7 +54,7 @@ Welcome to bumblebee-status's documentation!
    themes
    development/index
 
-   src/modules
+   api
 
 Indices and tables
 ==================
diff --git a/docs/introduction.rst b/docs/introduction.rst
index c8b84b7..9b1fcf7 100644
--- a/docs/introduction.rst
+++ b/docs/introduction.rst
@@ -1,41 +1,6 @@
 Introduction
 ================
 
-General
-----------------
-bumblebee-status is a modular, theme-able status line generator for the
-`i3 window manager <https://i3wm.org/>`__.
-
-Focus is on:
-
- - ease of use, sane defaults (no mandatory configuration file)
- - custom modules: :doc:`development/module`
- - custom themes: :doc:`development/theme`
- 
-I hope you like it and I appreciate any kind of feedback: bug reports,
-feature requests, etc. :)
-
-Thanks a lot!
-
-Required i3wm version: 4.12+ (in earlier versions, blocks won’t have
-background colors)
-
-Supported Python versions: 3.4, 3.5, 3.6, 3.7, 3.8
-
-Supported FontAwesome version: 4 (free version of 5 doesn’t include some
-of the icons)
-
-Example usage:
-
-.. code-block::
-
-   bar {
-       status_command <path>/bumblebee-status \
-        -m cpu memory battery time pasink pasource \
-        -p time.format="%H:%M" \
-        -t solarized
-   }
-
 Installation
 ----------------
 
@@ -124,8 +89,3 @@ As a simple example, this is what my i3 configuration looks like:
 
 Restart i3wm and - that’s it!
 
-Examples
----------
-
-.. include:: themes.rst
-
diff --git a/docs/other/NOTES.md b/docs/other/NOTES.md
index b758b16..8e7aa1c 100644
--- a/docs/other/NOTES.md
+++ b/docs/other/NOTES.md
@@ -21,3 +21,5 @@
 
 # documentation
 Add info about error widget and events for error logging
+- generate rst instead of markdown (list of modules)
+- add module contributor doc
diff --git a/docs/themes.rst b/docs/themes.rst
index 53beb10..7d2d62e 100644
--- a/docs/themes.rst
+++ b/docs/themes.rst
@@ -1,7 +1,5 @@
-Themes
-======
-
-Here are some screenshots of various themes:
+List of available themes
+========================
 
 .. warning:: Some themes (e.g. all ‘powerline’ themes) require `Font
     Awesome <http://fontawesome.io/>`__ and a powerline-compatible font