diff --git a/.gitignore b/.gitignore
index f5ab617ad5ed2ca6b7a0b112f12891b2f3774270..ed594580adf99a4c92b3d05ec94472c8541fb300 100644
--- a/.gitignore
+++ b/.gitignore
@@ -11,3 +11,4 @@ server.url
 /vagrant
 /tools/wa_user_directory/dependencies
 /src/buildroot
+_build
diff --git a/doc/bisector b/doc/bisector
new file mode 120000
index 0000000000000000000000000000000000000000..463efb3266f799e25c0809159e53370db78383b9
--- /dev/null
+++ b/doc/bisector
@@ -0,0 +1 @@
+../tools/bisector/doc
\ No newline at end of file
diff --git a/doc/bisector.rst b/doc/bisector.rst
index ca82e213be5b3af2354fcec1542239abf181879a..4e38d2cb87b9081fd71c093edcff0125b7621feb 100644
--- a/doc/bisector.rst
+++ b/doc/bisector.rst
@@ -1,7 +1,14 @@
+
+.. This shim allows including the tool's documentation as one entity in LISA
+   documentation. A plain ".. include::" would break relative paths.
+
+.. _bisector-doc:
+
 ********
 Bisector
 ********
 
-.. TODO:: write me
+.. toctree::
+   :maxdepth: 2
 
-**(This page is being worked on, come back later!)**
+   bisector/index
diff --git a/doc/conf.py b/doc/conf.py
index a6528259efbfd6e5f175dde43c13b5f407479df0..8cd3eaed30bfed047d810db489c54f8fc3ddff09 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -12,14 +12,11 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
-import itertools
 import logging
 import os
 import re
 import subprocess
 import sys
-import inspect
-import tempfile
 import unittest
 
 from docutils import nodes
@@ -33,6 +30,9 @@ sys.path.insert(0, os.path.abspath('../'))
 
 # Import our packages after modifying sys.path
 import lisa
+from lisa.doc.helpers import (
+    autodoc_process_test_method, autodoc_process_analysis_events
+)
 
 # This ugly hack is required because by default TestCase.__module__ is
 # equal to 'case', so sphinx replaces all of our TestCase uses to
@@ -356,111 +356,8 @@ autodoc_default_options = {
 }
 autodoc_inherit_docstrings = True
 
-def is_test(method):
-    if not callable(method):
-        return False
-
-    if method.__name__.startswith('test_'):
-        return True
-
-    # Tests are methods with an annotated return type, with at least
-    # one base class with a name containing 'result'
-    try:
-        ret_type = method.__annotations__['return']
-        base_cls_list = inspect.getmro(ret_type)
-    except (AttributeError, KeyError):
-        return False
-    else:
-        return any(
-            'result' in cls.__qualname__.lower()
-            for cls in base_cls_list
-        )
-
-def autodoc_process_test_method(app, what, name, obj, options, lines):
-    # Append the list of available test methods for all classes that appear to
-    # have some.
-    if what == 'class':
-        test_list = [
-            member
-            for member_name, member in inspect.getmembers(obj, is_test)
-        ]
-        if test_list:
-            test_list_doc = '\n:Test methods:\n\n{}\n\n'.format('\n'.join(
-                '    * :meth:`~{}`'.format(
-                    method.__module__ + '.' + method.__qualname__
-                )
-                for method in test_list
-            ))
-
-            lines.extend(test_list_doc.splitlines())
-
-def autodoc_process_analysis_events(app, what, name, obj, options, lines):
-    # Append the list of required trace events
-    if what != 'method' or not hasattr(obj, "used_events"):
-        return
-
-    events_doc = "\n:Required trace events:\n\n{}\n\n".format(obj.used_events.doc_str())
-    lines.extend(events_doc.splitlines())
-
 def setup(app):
     app.connect('autodoc-process-docstring', autodoc_process_test_method)
     app.connect('autodoc-process-docstring', autodoc_process_analysis_events)
 
-
-def get_test_id_list():
-    import lisa.tests as test_package
-    rst_list = []
-    for path in test_package.__path__:
-        rst_list.extend(subprocess.check_output((
-            'exekall', 'run', path,
-            '--rst-list', '--inject-empty-target-conf',
-            ), stderr=subprocess.STDOUT).decode('utf-8').splitlines()
-        )
-    return rst_list
-
-def get_analysis_list(prefix):
-    from lisa.analysis.base import TraceAnalysisBase
-    from lisa.utils import get_subclasses
-
-    rst_list = []
-
-    for subclass in get_subclasses(TraceAnalysisBase):
-        class_path = "{}.{}".format(subclass.__module__, subclass.__qualname__)
-        analysis = subclass.__module__.split(".")[-1]
-        meth_list = [name for name, member in inspect.getmembers(subclass, callable)
-                     if name.startswith(prefix)]
-
-        rst_list += [":class:`{0}<{1}>`::meth:`~{1}.{2}`".format(analysis, class_path, meth)
-                     for meth in meth_list]
-
-    return rst_list
-
-def get_analysis_df_list():
-    return get_analysis_list("df_")
-
-def get_analysis_plot_list():
-    return get_analysis_list("plot_")
-
-def create_doc_list_file(path, list_generator):
-    content = '\n'.join(
-        '* {}'.format(item)
-        for item in list_generator()
-    )
-
-    with open(path, 'wt') as f:
-        f.write(content + '\n')
-
-def create_test_list_file(path):
-    try:
-        create_doc_list_file(path, get_test_id_list)
-    except FileNotFoundError:
-        content = 'Please install exekall in order to generate the list of tests.'
-        print('WARNING: could not generate the list of test without exekall', file=sys.stderr)
-        with open(path, 'wt') as f:
-            f.write(content + '\n')
-
-create_test_list_file('test_list.rst')
-create_doc_list_file('analysis_df_list.rst', get_analysis_df_list)
-create_doc_list_file('analysis_plot_list.rst', get_analysis_plot_list)
-
 # vim :set tabstop=4 shiftwidth=4 textwidth=80 expandtab:
diff --git a/doc/exekall b/doc/exekall
new file mode 120000
index 0000000000000000000000000000000000000000..aa5ea274a902b52bf7d8ece77cdf7bc28d34d75b
--- /dev/null
+++ b/doc/exekall
@@ -0,0 +1 @@
+../tools/exekall/doc/
\ No newline at end of file
diff --git a/doc/exekall.rst b/doc/exekall.rst
index 05055200a01ca3f2738079e2cb2aff10c29dc98e..92d365e40c60ee712f3257d99ce91f33816fb0ed 100644
--- a/doc/exekall.rst
+++ b/doc/exekall.rst
@@ -1,7 +1,14 @@
+
+.. This shim allows including the tool's documentation as one entity in LISA
+   documentation. A plain ".. include::" would break relative paths.
+   
+.. _exekall-doc:
+
 *******
 Exekall
 *******
 
-.. TODO:: write me
+.. toctree::
+   :maxdepth: 2
 
-**(This page is being worked on, come back later!)**
+   exekall/index
diff --git a/doc/index.rst b/doc/index.rst
index 90b7356148256e258c3416c64cdaab2232e9f88c..8a1e71188f392b1e9a5a30b92ef7f261f9978644 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -25,8 +25,6 @@ via Github pull requests.
 
 Contents:
 
-.. TODO: Move wiki to here, wirte a proper module doc, proove Riemann's hypothesis
-
 .. toctree::
    :maxdepth: 2
 
diff --git a/doc/kernel_tests.rst b/doc/kernel_tests.rst
index c7ed538c12ec9975a666b46bd40892f0c4c91a28..c5f659ff32d2dc1cedd09a62c7448e27c5b76bfb 100644
--- a/doc/kernel_tests.rst
+++ b/doc/kernel_tests.rst
@@ -35,7 +35,10 @@ The following tests are available. They can be used as:
   * the individual classes/methods they are composed of can be used in custom
     scripts/jupyter notebooks (see ipynb/tests/synthetics_example.ipynb)
 
-.. include:: test_list.rst
+.. run-command::
+  :capture-stderr:
+  
+  exekall run $LISA_HOME/lisa/tests --rst-list --inject-empty-target-conf
 
 Running tests
 =============
diff --git a/doc/man1/bisector.1 b/doc/man1/bisector.1
new file mode 100644
index 0000000000000000000000000000000000000000..151ec61833e10c9d46fbf32b2f95d3c394f59617
--- /dev/null
+++ b/doc/man1/bisector.1
@@ -0,0 +1,1158 @@
+.\" Man page generated from reStructuredText.
+.
+.TH "BISECTOR" "1" "2019" "" "bisector"
+.SH NAME
+bisector \- command sequencer
+.
+.nr rst2man-indent-level 0
+.
+.de1 rstReportMargin
+\\$1 \\n[an-margin]
+level \\n[rst2man-indent-level]
+level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
+-
+\\n[rst2man-indent0]
+\\n[rst2man-indent1]
+\\n[rst2man-indent2]
+..
+.de1 INDENT
+.\" .rstReportMargin pre:
+. RS \\$1
+. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
+. nr rst2man-indent-level +1
+.\" .rstReportMargin post:
+..
+.de UNINDENT
+. RE
+.\" indent \\n[an-margin]
+.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.nr rst2man-indent-level -1
+.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
+..
+.SH DESCRIPTION
+.sp
+\fBbisector\fP is a \fBgit bisect run\fP [1] compatible tool used in LISA. Its goal is
+to sequence commands to be repeated an arbitrary number of times and generates
+a report.
+.sp
+For example, \fBbisector\fP can be used to compile a kernel, flash a board,
+reboot it and run test suite. To achieve that, \fBbisector\fP runs a sequence of
+steps, and saves a report file containing the result of each step. This step
+sequence is run for a number of iterations, or for a given duration. That
+allows tracking fluctuating bugs by repeating a test process many times.
+.sp
+The steps class can implement any run or report behavior, with the ability to
+take parameters. They also decide what data is saved into the report, and
+their contribution to the overall \fBgit bisect\fP result:
+.INDENT 0.0
+.IP \(bu 2
+\fIgood\fP: the test steps passed
+.IP \(bu 2
+\fIbad\fP: the test steps failed
+.IP \(bu 2
+\fIuntestable\fP: the build or flash step failed
+.IP \(bu 2
+\fIabort\fP: the reboot step failed, and the board is now unusable and requires
+manual intervention
+.IP \(bu 2
+\fINA\fP: the step will not impact the overall result
+.UNINDENT
+.sp
+It is important to note that \fBbisector\fP step classes usually only invoke a
+user\-specified command line tool and will use the return code to decide what
+\fBgit bisect\fP result to return. They can also implement more specific result
+reporting, and additional run behaviors.
+.SH OPTIONS
+.SS bisector
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+usage: bisector [\-h] [\-\-cli\-options CLI_OPTIONS]
+                {step\-help,run,report,edit,monitor\-server,monitor} ...
+
+    Git\-bisect\-compatible command sequencer.
+
+    bisector allows to run commands with timeout handling in predefined
+    sequences (steps). The output is saved in a report that can be later
+    analyzed. The exit status of all steps is merged to obtain a git bisect
+    compatible value which is returned. The error code 254 is used
+    when bisector itself encounters an error.
+
+    SIGNAL HANDLING
+
+    The script can be stopped with SIGINT (Ctrl\-C) or SIGTERM (kill or timeout
+    commands) or SIGHUP (when the terminal dies) and will save the completed
+    iterations to the report. The execution can later be resumed with \-\-resume.
+    
+
+optional arguments:
+  \-h, \-\-help            show this help message and exit
+  \-\-cli\-options CLI_OPTIONS
+                        YAML file containing command line option string in a
+                        "cmd\-line" toplevel key. Therefore, the same file can be used
+                        for \-\-steps.  The options are inserted at the location of
+                        \-\-cli\-options in the command line. That can be used to control what
+                        can be overriden by configuration file and what is forced by the
+                        command line
+
+subcommands:
+  {step\-help,run,report,edit,monitor\-server,monitor}
+
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SS bisector run
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+usage: bisector run [\-h] [\-\-cli\-options CLI_OPTIONS] [\-o OPTION] [\-\-debug]
+                    [\-\-steps STEPS] [\-\-allowed\-bad ALLOWED_BAD] [\-\-skip SKIP]
+                    [\-\-only ONLY] [\-\-git\-clean] [\-\-inline CLASS NAME]
+                    [\-n ITERATIONS] [\-\-timeout TIMEOUT] [\-\-log LOG]
+                    [\-\-report REPORT] [\-\-overwrite] [\-\-resume] [\-\-desc DESC]
+                    [\-\-early\-bailout] [\-\-upload\-report] [\-\-no\-dbus]
+
+Run the given steps in a loop and record the result in a report file. The
+report file can be inspected using the "report" subcommand. The exit status is
+suitable for git bisect.
+
+optional arguments:
+  \-h, \-\-help            show this help message and exit
+  \-\-cli\-options CLI_OPTIONS
+                        YAML file containing command line option string in a
+                        "cmd\-line" toplevel key. Therefore, the same file can
+                        be used for \-\-steps. The options are inserted at the
+                        location of \-\-cli\-options in the command line. That
+                        can be used to control what can be overriden by
+                        configuration file and what is forced by the command
+                        line
+  \-o OPTION, \-\-option OPTION
+                        Step\-specific options. Can be repeated. The format is
+                        <step category or name pattern>.<option>=<value>. If
+                        the step name or category is omitted, it will be
+                        passed to all steps. See "step\-help" subcommand for
+                        the available options. Options specified this way
+                        override the steps definition file, and can be used to
+                        modify the report when used with run \-\-resume or edit
+                        subcommand.
+  \-\-debug               Show Python traceback to help debugging this script.
+  \-\-steps STEPS         YAML configuration of steps to run. The steps
+                        definitions lives under a "step" toplevel key.
+  \-\-allowed\-bad ALLOWED_BAD
+                        Percentage of bad iterations that still result in a
+                        good overall result.
+  \-\-skip SKIP           Step name or category to skip. Can be repeated.
+  \-\-only ONLY           Step name or category to execute. Can be repeated.
+  \-\-git\-clean           Run git reset \-\-hard and git clean \-fdx before and
+                        after the steps are executed. It is useful for
+                        automated bisect to avoid checkout failure that leads
+                        to bisect abortion. WARNING: this will erase all
+                        changes and untracked files from the worktree.
+  \-\-inline CLASS NAME, \-s CLASS NAME
+                        Class and name of inline step. Can be repeated to
+                        build a list of steps in the order of appearance.
+  \-n ITERATIONS, \-\-iterations ITERATIONS
+                        Number of iterations. "inf" means an infinite number
+                        of iterations.
+  \-\-timeout TIMEOUT     Timeout after which no more itertions will be started.
+                        "inf" means infinite timeout (i.e. no timeout).
+  \-\-log LOG             Log all events to the log file. By default, a log file
+                        is created as <report file>.log .
+  \-\-report REPORT       Execution report containing output and return values
+                        for all steps. Can be displayed using the "report"
+                        subcommand. The {commit} placeholder is replaced with
+                        the truncated sha1 of HEAD in current directory, and
+                        {date} by a string built from the current date and
+                        time. If the file name ends with .pickle or
+                        .pickle.gz, a Pickle file is created, otherwise YAML
+                        format is used. YAML is good for archiving but slow to
+                        generate and load, Pickle format cannot expected to be
+                        backward compatible with different versions of the
+                        tool but can be faster to read and write. CAVEAT:
+                        Pickle format will not handle references to modules
+                        that are not in sys.path.
+  \-\-overwrite           Overwrite existing report files.
+  \-\-resume              Resume execution from the report specified with
+                        \-\-report. The steps will be extracted from the report
+                        instead of from the command line. The number of
+                        completed iterations will be deducted from the
+                        specified number of iterations.
+  \-\-desc DESC           Report description. Can use {commit} and {date}
+                        placeholders.
+  \-\-early\-bailout       Restart a new iteration if a step marked the commit as
+                        bad or non\-testable. Bisect abortion will still take
+                        place even without this option.
+  \-\-upload\-report       Continuously upload the report to Artifactorial after
+                        every iteration. This relies on the following
+                        environment variables: ARTIFACTORIAL_FOLDER set to the
+                        folder\(aqs URL and ARTIFACTORIAL_TOKEN set to the token.
+                        Remember to use the right step option to upload the
+                        results as they are computed if desired.
+  \-\-no\-dbus             Disable DBus even when pydbus module is available.
+
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SS bisector report
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+usage: bisector report [\-h] [\-\-cli\-options CLI_OPTIONS] [\-o OPTION] [\-\-debug]
+                       [\-\-steps STEPS] [\-\-allowed\-bad ALLOWED_BAD]
+                       [\-\-skip SKIP] [\-\-only ONLY] [\-\-export EXPORT] [\-\-cache]
+                       report
+
+Analyze a report generated by run command. The exit status is suitable for git
+bisect. In most cases, step options (\(ga\(ga\-o\(ga\(ga) will act as filters to ignore
+parts of the data before computing the overall bisect result.
+
+positional arguments:
+  report                Read back a previous session saved using \-\-report
+                        option of run subcommand.
+
+optional arguments:
+  \-h, \-\-help            show this help message and exit
+  \-\-cli\-options CLI_OPTIONS
+                        YAML file containing command line option string in a
+                        "cmd\-line" toplevel key. Therefore, the same file can
+                        be used for \-\-steps. The options are inserted at the
+                        location of \-\-cli\-options in the command line. That
+                        can be used to control what can be overriden by
+                        configuration file and what is forced by the command
+                        line
+  \-o OPTION, \-\-option OPTION
+                        Step\-specific options. Can be repeated. The format is
+                        <step category or name pattern>.<option>=<value>. If
+                        the step name or category is omitted, it will be
+                        passed to all steps. See "step\-help" subcommand for
+                        the available options. Options specified this way
+                        override the steps definition file, and can be used to
+                        modify the report when used with run \-\-resume or edit
+                        subcommand.
+  \-\-debug               Show Python traceback to help debugging this script.
+  \-\-steps STEPS         YAML configuration of steps to run. The steps
+                        definitions lives under a "step" toplevel key.
+  \-\-allowed\-bad ALLOWED_BAD
+                        Percentage of bad iterations that still result in a
+                        good overall result.
+  \-\-skip SKIP           Step name or category to skip. Can be repeated.
+  \-\-only ONLY           Step name or category to execute. Can be repeated.
+  \-\-export EXPORT       Export the report as a Pickle or YAML file. File
+                        format is infered from the filename. If it ends with
+                        .pickle, a Pickle file is created, otherwise YAML
+                        format is used.
+  \-\-cache               When loading a report, create a cache file named
+                        "{report_filename}.cache.pickle" using the fastest
+                        format available. It is the reused until the original
+                        file is modified. This is mostly useful when working
+                        with big YAML files that are long to load.
+
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SS bisector step\-help
+.sp
+Steps\-specific options to be used with \fBbisector run \-o\fP and \fBbisector report \-o\fP\&.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+
+LISA\-test (test)
+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
+Inherits from: shell
+
+    Execute a LISA test command and collect xUnit results. Also compress the
+    result directory and record its path. It will also define some environment
+    variables that are expected to be used by the command to be able to locate
+    resources to collect.
+    
+    .. deprecated:: 1.0
+        This class is designed for legacy LISA, use
+        :class:\(gaExekallLISATestStep\(ga for current LISA instead.
+
+    run:
+      \-o bail\-out= (bool) 
+            start a new iteration if the command fails, without executing
+            remaining steps for this iteration
+
+      \-o cmd= (non\-empty str) 
+            shell command to be executed
+
+      \-o compress\-results= (bool) 
+            compress the LISA result directory in an archive
+
+      \-o env= (env var list) 
+            environment variables with a list of values that will be used for
+            each iterations, wrapping around. The string format is:
+            VAR1=val1%val2%...%%VAR2=val1%val2%.... In YAML, it is a map of var
+            names to list of values. A single string can be supplied instead of
+            a list of values.
+
+      \-o kill\-timeout= (int or "inf") 
+            time to wait before sending SIGKILL after having sent SIGTERM
+
+      \-o shell= (non\-empty str) 
+            shell to execute the command in
+
+      \-o timeout= (int or "inf") 
+            timeout in seconds before sending SIGTERM to the command, or "inf"
+            for infinite timeout
+
+      \-o trials= (int) 
+            number of times the command will be retried if it does not return 0
+
+      \-o upload\-results= (bool) 
+            upload the LISA results directory to Artifactorial as the execution
+            goes, and delete the local archive.
+
+      \-o use\-systemd\-run= (bool) 
+            use systemd\-run to run the command. This allows cleanup of daemons
+            spawned by the command (using cgroups), and using a private /tmp
+            that is also cleaned up automatically
+
+
+    report:
+      \-o download= (bool) 
+            Download the LISA results archives if necessary
+
+      \-o dump\-results\-dir= (non\-empty str) 
+            write the list of LISA result directories to a file. Useful to
+            implement garbage collection of unreferenced results archives
+
+      \-o export\-logs= (non\-empty str) 
+            export the logs, xUnit file and result dir symlink to the given
+            directory
+
+      \-o ignore\-excep= (comma\-separated list) 
+            ignore the given comma\-separated list of exceptions that caused
+            tests failure or error. * can be used to match any part of the name
+
+      \-o ignore\-non\-issue= (bool) 
+            consider only tests that failed
+
+      \-o iterations= (comma\-separated list of integer ranges) 
+            comma\-separated list of iterations to consider. Inclusive ranges can
+            be specified with <first>\-<last>
+
+      \-o show\-basic= (bool) 
+            show command exit status for all iterations
+
+      \-o show\-details= ("msg" or bool) 
+            show details of erros and failures. Use "msg" for only a brief
+            message
+
+      \-o show\-dist= (bool) 
+            show graphical distribution of issues among iterations with a one
+            letter code: passed=".", failed="F", error="#", skipped="s"
+
+      \-o show\-pass\-rate= (bool) 
+            always show the pass rate of tests, even when there are failures or
+            crashes as well
+
+      \-o show\-rates= (bool) 
+            show percentages of failure, error, skipped and passed tests
+
+      \-o show\-results\-dir= (bool) 
+            show LISA result directory for all iterations
+
+      \-o testcase= (comma\-separated list) 
+            show only the test cases matching one of the patterns in the comma\-
+            separated list. * can be used to match any part of the name.
+
+      \-o upload\-results= (bool) 
+            upload the results directory to Artifactorial and update the in\-
+            memory report. Following env var are needed: ARTIFACTORIAL_FOLDER
+            set to the folder URL and ARTIFACTORIAL_TOKEN. Note: \-\-export should
+            be used to save the report with updated paths
+
+      \-o verbose= (bool) 
+            increase verbosity
+
+      \-o xunit2json= (non\-empty str) 
+            append consolidated xUnit information to a JSON file
+
+
+
+build (build)
+\-\-\-\-\-\-\-\-\-\-\-\-\-
+Inherits from: shell
+
+    Similar to :class:\(gaShellStep\(ga .
+    
+    Non\-zero exit status of the command will be interpreted as a bisect
+    untestable status, and zero exit status as bisect good.
+
+    run:
+      \-o bail\-out= (bool) 
+            start a new iteration if the command fails, without executing
+            remaining steps for this iteration
+
+      \-o cmd= (non\-empty str) 
+            shell command to be executed
+
+      \-o env= (env var list) 
+            environment variables with a list of values that will be used for
+            each iterations, wrapping around. The string format is:
+            VAR1=val1%val2%...%%VAR2=val1%val2%.... In YAML, it is a map of var
+            names to list of values. A single string can be supplied instead of
+            a list of values.
+
+      \-o kill\-timeout= (int or "inf") 
+            time to wait before sending SIGKILL after having sent SIGTERM
+
+      \-o shell= (non\-empty str) 
+            shell to execute the command in
+
+      \-o timeout= (int or "inf") 
+            timeout in seconds before sending SIGTERM to the command, or "inf"
+            for infinite timeout
+
+      \-o trials= (int) 
+            number of times the command will be retried if it does not return 0
+
+      \-o use\-systemd\-run= (bool) 
+            use systemd\-run to run the command. This allows cleanup of daemons
+            spawned by the command (using cgroups), and using a private /tmp
+            that is also cleaned up automatically
+
+
+    report:
+      \-o export\-logs= (non\-empty str) 
+            export the logs to the given directory
+
+      \-o ignore\-non\-issue= (bool) 
+            consider only iteration with non\-zero command exit status
+
+      \-o iterations= (comma\-separated list of integer ranges) 
+            comma\-separated list of iterations to consider. Inclusive ranges can
+            be specified with <first>\-<last>
+
+      \-o show\-basic= (bool) 
+            show command exit status for all iterations
+
+      \-o verbose= (bool) 
+            increase verbosity
+
+
+
+exekall\-LISA\-test (test)
+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
+Inherits from: shell
+
+    Execute an exekall LISA test command and collect
+    :class:\(gaexekall.engine.ValueDB\(ga. Also compress the result directory and
+    record its path. It will also define some environment variables that are
+    expected to be used by the command to be able to locate resources to
+    collect.
+
+    run:
+      \-o bail\-out= (bool) 
+            start a new iteration if the command fails, without executing
+            remaining steps for this iteration
+
+      \-o cmd= (non\-empty str) 
+            shell command to be executed
+
+      \-o compress\-artifact= (bool) 
+            compress the exekall artifact directory in an archive
+
+      \-o delete\-artifact= (bool) 
+            delete the exekall artifact directory to Artifactorial as the
+            execution goes.
+
+      \-o env= (env var list) 
+            environment variables with a list of values that will be used for
+            each iterations, wrapping around. The string format is:
+            VAR1=val1%val2%...%%VAR2=val1%val2%.... In YAML, it is a map of var
+            names to list of values. A single string can be supplied instead of
+            a list of values.
+
+      \-o kill\-timeout= (int or "inf") 
+            time to wait before sending SIGKILL after having sent SIGTERM
+
+      \-o prune\-db= (bool) 
+            Prune exekall\(aqs ValueDB so that only roots values are preserved.
+            That allows smaller reports that are faster to load
+
+      \-o shell= (non\-empty str) 
+            shell to execute the command in
+
+      \-o timeout= (int or "inf") 
+            timeout in seconds before sending SIGTERM to the command, or "inf"
+            for infinite timeout
+
+      \-o upload\-artifact= (bool) 
+            upload the exekall artifact directory to Artifactorial as the
+            execution goes, and delete the local archive.
+
+      \-o use\-systemd\-run= (bool) 
+            use systemd\-run to run the command. This allows cleanup of daemons
+            spawned by the command (using cgroups), and using a private /tmp
+            that is also cleaned up automatically
+
+
+    report:
+      \-o download= (bool) 
+            Download the exekall artifact archives if necessary
+
+      \-o dump\-artifact\-dirs= (non\-empty str) 
+            write the list of exekall artifact directories to a file. Useful to
+            implement garbage collection of unreferenced artifact archives
+
+      \-o export\-db= (non\-empty str) 
+            export a merged exekall ValueDB, merging it with existing ValueDB if
+            the file exists
+
+      \-o export\-logs= (non\-empty str) 
+            export the logs and artifact directory symlink to the given
+            directory
+
+      \-o ignore\-excep= (comma\-separated list) 
+            ignore the given comma\-separated list of exceptions class name
+            patterns that caused tests error. This will also match on base
+            classes of the exception.
+
+      \-o ignore\-non\-error= (bool) 
+            consider only tests that had an error
+
+      \-o ignore\-non\-issue= (bool) 
+            consider only tests that failed or had an error
+
+      \-o ignore\-testcase= (comma\-separated list) 
+            completely ignore test cases matching one of the patterns in the
+            comma\-separated list. * can be used to match any part of the name.
+
+      \-o iterations= (comma\-separated list of integer ranges) 
+            comma\-separated list of iterations to consider. Inclusive ranges can
+            be specified with <first>\-<last>
+
+      \-o show\-artifact\-dirs= (bool) 
+            show exekall artifact directory for all iterations
+
+      \-o show\-basic= (bool) 
+            show command exit status for all iterations
+
+      \-o show\-details= ("msg" or bool) 
+            show details of results. Use "msg" for only a brief message
+
+      \-o show\-dist= (bool) 
+            show graphical distribution of issues among iterations with a one
+            letter code: passed=".", failed="F", error="#", skipped="s",
+            undecided="u"
+
+      \-o show\-pass\-rate= (bool) 
+            always show the pass rate of tests, even when there are failures or
+            errors as well
+
+      \-o show\-rates= (bool) 
+            show percentages of failure, error, skipped, undecided and passed
+            tests
+
+      \-o testcase= (comma\-separated list) 
+            show only the test cases matching one of the patterns in the comma\-
+            separated list. * can be used to match any part of the name
+
+      \-o upload\-artifact= (bool) 
+            upload the artifact directory to Artifactorial and update the in\-
+            memory report. Following env var are needed: ARTIFACTORIAL_FOLDER
+            set to the folder URL and ARTIFACTORIAL_TOKEN. Note: \-\-export should
+            be used to save the report with updated paths
+
+      \-o verbose= (bool) 
+            increase verbosity
+
+
+
+flash (flash)
+\-\-\-\-\-\-\-\-\-\-\-\-\-
+Inherits from: shell
+
+    Similar to :class:\(gaShellStep\(ga .
+    
+    Non\-zero exit status of the command will be interpreted as a bisect
+    abort, and zero exit status ignored.
+
+    run:
+      \-o bail\-out= (bool) 
+            start a new iteration if the command fails, without executing
+            remaining steps for this iteration
+
+      \-o cmd= (non\-empty str) 
+            shell command to be executed
+
+      \-o env= (env var list) 
+            environment variables with a list of values that will be used for
+            each iterations, wrapping around. The string format is:
+            VAR1=val1%val2%...%%VAR2=val1%val2%.... In YAML, it is a map of var
+            names to list of values. A single string can be supplied instead of
+            a list of values.
+
+      \-o kill\-timeout= (int or "inf") 
+            time to wait before sending SIGKILL after having sent SIGTERM
+
+      \-o shell= (non\-empty str) 
+            shell to execute the command in
+
+      \-o timeout= (int or "inf") 
+            timeout in seconds before sending SIGTERM to the command, or "inf"
+            for infinite timeout
+
+      \-o trials= (int) 
+            number of times the command will be retried if it does not return 0
+
+      \-o use\-systemd\-run= (bool) 
+            use systemd\-run to run the command. This allows cleanup of daemons
+            spawned by the command (using cgroups), and using a private /tmp
+            that is also cleaned up automatically
+
+
+    report:
+      \-o export\-logs= (non\-empty str) 
+            export the logs to the given directory
+
+      \-o ignore\-non\-issue= (bool) 
+            consider only iteration with non\-zero command exit status
+
+      \-o iterations= (comma\-separated list of integer ranges) 
+            comma\-separated list of iterations to consider. Inclusive ranges can
+            be specified with <first>\-<last>
+
+      \-o show\-basic= (bool) 
+            show command exit status for all iterations
+
+      \-o verbose= (bool) 
+            increase verbosity
+
+
+
+macro (macro)
+\-\-\-\-\-\-\-\-\-\-\-\-\-
+    Provide a loop\-like construct to the steps definitions.
+    
+    All sub\-steps will be executed in order. This sequence will be repeated
+    for the given number of iterations or until it times out. The steps
+    definition YAML configuration file is interpreted assuming an implicit
+    toplevel :class:\(gaMacroStep\(ga that is parameterized using command line options.
+
+    run:
+      \-o bail\-out\-early= (bool) 
+            start a new iteration when a step returned bisect status bad or
+            untestable and skip all remaining steps
+
+      \-o iterations= (int or "inf") 
+            number of iterations
+
+      \-o timeout= (int or "inf") 
+            time after which no new iteration will be started
+
+
+
+reboot (boot)
+\-\-\-\-\-\-\-\-\-\-\-\-\-
+Inherits from: shell
+
+    Similar to :class:\(gaShellStep\(ga .
+    
+    Non\-zero exit status of the command will be interpreted as a bisect
+    abort, and zero exit status as bisect good.
+
+    run:
+      \-o bail\-out= (bool) 
+            start a new iteration if the command fails, without executing
+            remaining steps for this iteration
+
+      \-o cmd= (non\-empty str) 
+            shell command to be executed
+
+      \-o env= (env var list) 
+            environment variables with a list of values that will be used for
+            each iterations, wrapping around. The string format is:
+            VAR1=val1%val2%...%%VAR2=val1%val2%.... In YAML, it is a map of var
+            names to list of values. A single string can be supplied instead of
+            a list of values.
+
+      \-o kill\-timeout= (int or "inf") 
+            time to wait before sending SIGKILL after having sent SIGTERM
+
+      \-o shell= (non\-empty str) 
+            shell to execute the command in
+
+      \-o timeout= (int or "inf") 
+            timeout in seconds before sending SIGTERM to the command, or "inf"
+            for infinite timeout
+
+      \-o trials= (int) 
+            number of times the command will be retried if it does not return 0
+
+      \-o use\-systemd\-run= (bool) 
+            use systemd\-run to run the command. This allows cleanup of daemons
+            spawned by the command (using cgroups), and using a private /tmp
+            that is also cleaned up automatically
+
+
+    report:
+      \-o export\-logs= (non\-empty str) 
+            export the logs to the given directory
+
+      \-o ignore\-non\-issue= (bool) 
+            consider only iteration with non\-zero command exit status
+
+      \-o iterations= (comma\-separated list of integer ranges) 
+            comma\-separated list of iterations to consider. Inclusive ranges can
+            be specified with <first>\-<last>
+
+      \-o show\-basic= (bool) 
+            show command exit status for all iterations
+
+      \-o verbose= (bool) 
+            increase verbosity
+
+
+
+shell (shell)
+\-\-\-\-\-\-\-\-\-\-\-\-\-
+    Execute a command in a shell.
+    
+    Stdout and stderr are merged and logged. The exit status of the command
+    will have no influence of the bisect status.
+
+    run:
+      \-o bail\-out= (bool) 
+            start a new iteration if the command fails, without executing
+            remaining steps for this iteration
+
+      \-o cmd= (non\-empty str) 
+            shell command to be executed
+
+      \-o env= (env var list) 
+            environment variables with a list of values that will be used for
+            each iterations, wrapping around. The string format is:
+            VAR1=val1%val2%...%%VAR2=val1%val2%.... In YAML, it is a map of var
+            names to list of values. A single string can be supplied instead of
+            a list of values.
+
+      \-o kill\-timeout= (int or "inf") 
+            time to wait before sending SIGKILL after having sent SIGTERM
+
+      \-o shell= (non\-empty str) 
+            shell to execute the command in
+
+      \-o timeout= (int or "inf") 
+            timeout in seconds before sending SIGTERM to the command, or "inf"
+            for infinite timeout
+
+      \-o trials= (int) 
+            number of times the command will be retried if it does not return 0
+
+      \-o use\-systemd\-run= (bool) 
+            use systemd\-run to run the command. This allows cleanup of daemons
+            spawned by the command (using cgroups), and using a private /tmp
+            that is also cleaned up automatically
+
+
+    report:
+      \-o export\-logs= (non\-empty str) 
+            export the logs to the given directory
+
+      \-o ignore\-non\-issue= (bool) 
+            consider only iteration with non\-zero command exit status
+
+      \-o iterations= (comma\-separated list of integer ranges) 
+            comma\-separated list of iterations to consider. Inclusive ranges can
+            be specified with <first>\-<last>
+
+      \-o show\-basic= (bool) 
+            show command exit status for all iterations
+
+      \-o verbose= (bool) 
+            increase verbosity
+
+
+
+test (test)
+\-\-\-\-\-\-\-\-\-\-\-
+Inherits from: shell
+
+    Similar to :class:\(gaShellStep\(ga .
+    
+    Non\-zero exit status of the command will be interpreted as a bisect bad
+    status, and zero exit status as bisect good.
+
+    run:
+      \-o bail\-out= (bool) 
+            start a new iteration if the command fails, without executing
+            remaining steps for this iteration
+
+      \-o cmd= (non\-empty str) 
+            shell command to be executed
+
+      \-o env= (env var list) 
+            environment variables with a list of values that will be used for
+            each iterations, wrapping around. The string format is:
+            VAR1=val1%val2%...%%VAR2=val1%val2%.... In YAML, it is a map of var
+            names to list of values. A single string can be supplied instead of
+            a list of values.
+
+      \-o kill\-timeout= (int or "inf") 
+            time to wait before sending SIGKILL after having sent SIGTERM
+
+      \-o shell= (non\-empty str) 
+            shell to execute the command in
+
+      \-o timeout= (int or "inf") 
+            timeout in seconds before sending SIGTERM to the command, or "inf"
+            for infinite timeout
+
+      \-o trials= (int) 
+            number of times the command will be retried if it does not return 0
+
+      \-o use\-systemd\-run= (bool) 
+            use systemd\-run to run the command. This allows cleanup of daemons
+            spawned by the command (using cgroups), and using a private /tmp
+            that is also cleaned up automatically
+
+
+    report:
+      \-o export\-logs= (non\-empty str) 
+            export the logs to the given directory
+
+      \-o ignore\-non\-issue= (bool) 
+            consider only iteration with non\-zero command exit status
+
+      \-o iterations= (comma\-separated list of integer ranges) 
+            comma\-separated list of iterations to consider. Inclusive ranges can
+            be specified with <first>\-<last>
+
+      \-o show\-basic= (bool) 
+            show command exit status for all iterations
+
+      \-o verbose= (bool) 
+            increase verbosity
+
+
+
+yield (yield)
+\-\-\-\-\-\-\-\-\-\-\-\-\-
+    Abort current iteration with the yield return code.
+    
+    If the specified command returns a non\-zero return code, bisector will
+    abort the current iteration with the yield return code.
+    
+    .. note:: This step can only be used under the main macrostep (it cannot be
+        used in nested macrosteps).
+
+    run:
+      \-o bail\-out= (bool) 
+            start a new iteration if the command fails, without executing
+            remaining steps for this iteration
+
+      \-o cmd= (non\-empty str) 
+            shell command to be executed
+
+      \-o env= (env var list) 
+            environment variables with a list of values that will be used for
+            each iterations, wrapping around. The string format is:
+            VAR1=val1%val2%...%%VAR2=val1%val2%.... In YAML, it is a map of var
+            names to list of values. A single string can be supplied instead of
+            a list of values.
+
+      \-o every\-n\-iterations= (int) 
+            The step will be a no\-op except if the iteration number can be
+            evenly divided by that value.
+
+      \-o kill\-timeout= (int or "inf") 
+            time to wait before sending SIGKILL after having sent SIGTERM
+
+      \-o shell= (non\-empty str) 
+            shell to execute the command in
+
+      \-o timeout= (int or "inf") 
+            timeout in seconds before sending SIGTERM to the command, or "inf"
+            for infinite timeout
+
+      \-o trials= (int) 
+            number of times the command will be retried if it does not return 0
+
+      \-o use\-systemd\-run= (bool) 
+            use systemd\-run to run the command. This allows cleanup of daemons
+            spawned by the command (using cgroups), and using a private /tmp
+            that is also cleaned up automatically
+
+
+
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SS bisector monitor
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+usage: bisector monitor [\-h] [\-\-cli\-options CLI_OPTIONS] [\-\-status]
+                        [\-\-prop PROP] [\-\-list]
+                        [\-\-pause | \-\-stop | \-\-continue | \-\-kill | \-\-log | \-\-report ... | \-\-notif enable/disable PROPERTY]
+                        PID
+
+Monitor and control a running instance.
+
+positional arguments:
+  PID                   Slave PID to act on or "all". Start a monitor\-server
+                        before using "all".
+
+optional arguments:
+  \-h, \-\-help            show this help message and exit
+  \-\-cli\-options CLI_OPTIONS
+                        YAML file containing command line option string in a
+                        "cmd\-line" toplevel key. Therefore, the same file can
+                        be used for \-\-steps. The options are inserted at the
+                        location of \-\-cli\-options in the command line. That
+                        can be used to control what can be overriden by
+                        configuration file and what is forced by the command
+                        line
+  \-\-status              Show status.
+  \-\-prop PROP           Show given property.
+  \-\-list                List all slaves.
+  \-\-pause               Pause at the end of the iteration.
+  \-\-stop                Stop at the end of the iteration.
+  \-\-continue            Continue paused or stopped instance.
+  \-\-kill                Kill the given instance.
+  \-\-log                 Show log in $PAGER.
+  \-\-report ...          Equivalent to running bisector report, all remaining
+                        options being passed to it.
+  \-\-notif enable/disable PROPERTY
+                        Enable and disable desktop notifications when the
+                        given property changes. \(aqall\(aq will select all
+                        properties.
+
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SS bisector monitor\-server
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+usage: bisector monitor\-server [\-h] [\-\-cli\-options CLI_OPTIONS]
+                               [\-\-notif enable/disable PROPERTY]
+
+Start the DBus server to allow monitoring all running instances. Note that the
+server is not necessary to monitor a specific run instance.
+
+optional arguments:
+  \-h, \-\-help            show this help message and exit
+  \-\-cli\-options CLI_OPTIONS
+                        YAML file containing command line option string in a
+                        "cmd\-line" toplevel key. Therefore, the same file can
+                        be used for \-\-steps. The options are inserted at the
+                        location of \-\-cli\-options in the command line. That
+                        can be used to control what can be overriden by
+                        configuration file and what is forced by the command
+                        line
+  \-\-notif enable/disable PROPERTY
+                        Enable and disable desktop notifications when the
+                        given property changes. \(aqall\(aq will select all
+                        properties.
+
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SS bisector edit
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+usage: bisector edit [\-h] [\-o OPTION] [\-\-debug] [\-\-steps STEPS] report
+
+Modify the properties of the steps in an existing report.
+
+positional arguments:
+  report                Report to edit.
+
+optional arguments:
+  \-h, \-\-help            show this help message and exit
+  \-o OPTION, \-\-option OPTION
+                        Step\-specific options. Can be repeated. The format is
+                        <step category or name pattern>.<option>=<value>. If
+                        the step name or category is omitted, it will be
+                        passed to all steps. See "step\-help" subcommand for
+                        the available options. Options specified this way
+                        override the steps definition file, and can be used to
+                        modify the report when used with run \-\-resume or edit
+                        subcommand.
+  \-\-debug               Show Python traceback to help debugging this script.
+  \-\-steps STEPS         YAML configuration of steps used to find new paths of
+                        classes if necessary. It is otherwise ignored and
+                        \-\-option must be used to edit the report.
+
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SH CONFIGURATION
+.sp
+\fBbisector run\fP is configured using a YAML [2] file specified using \fB\-\-steps\fP that
+defines the steps that will be executed in a loop. Each declared step has a (usually
+unique) name and a class that will influence the way its result is used and its
+options.
+.sp
+The YAML file is structured as following:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+# Top\-level "steps" key is important as the same file can be used to host other
+# information.
+steps:
+
+   # build step will interpret a non\-zero exit status of the command as a
+   # bisect untestable status, and zero exit status as bisect good.
+    \-
+      class: BuildStep
+      cmd: make defconfig Image dtbs
+      trials: 1
+
+   # flash step will interpret a non\-zero exit status of the command as a
+   # bisect abort, and zero exit status ignored.
+   \-
+      class: FlashStep
+      cmd: flash\-my\-board
+      timeout: 180
+      trials: 5
+
+   # reboot step will interpret a non\-zero exit status of the command as a
+   # bisect abort, and zero exit status as bisect good.
+    \-
+      class: reboot
+      timeout: 300
+      trials: 10
+      cmd: reboot\-my\-board
+
+    # exekall LISA test will interpret a non\-zero exit status of the command
+    # as bisect bad, and a zero exit status as bisect good.
+    \-
+      class: exekall\-LISA\-test
+      name: one\-small\-task
+      # Using systemd\-run ensures all child process is killed if the session
+      # is interrupted
+      use\-systemd\-run: true
+      timeout: 3600
+      cmd: lisa\-test \(aqOneSmallTask*\(aq
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+All step options can also be specified using \fB\-\-options/\-o\fP, which will
+override what is described in the YAML steps configuration.
+.SH MONITORING
+.sp
+\fBbisector run\fP allows some live monitoring by exposing a DBus interface. This
+is used by two subcommands: \fBbisector monitor\-server\fP and \fBbisector
+monitor\fP\&.
+.SS Server
+.sp
+\fBbisector monitor\-server\fP acts as a registry of all \fBbisector run\fP
+executing under the same user (DBus session bus). It allows \fBbisector
+monitor\fP to list active instances and also forwards desktop notifications to
+the desktop environment. The server can be (re)started after \fBbisector run\fP
+if necessary.
+.SS Monitor
+.sp
+\fBbisector monitor\fP allows listing active instances of \fBbisector run\fP (when
+the server is running), and allows querying various information from them.
+Since the query can be directed to a specific PID, the server is only necessary
+for listing.
+.SH EXAMPLES
+.sp
+A typical flow of \fBbisector\fP looks like that:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+# Run the steps and generate a report.
+# systemd\-run will be used for all steps by using "\-o" without specifying a
+step name or category.
+bisector run \-\-desc "description of my report" \-\-steps bisector_steps.yaml \-\-report bisector.report.yml.gz \-ouse\-systemd\-run=yes
+
+# Later inspection of the report, only looking at the steps that have "test"
+# name or category.
+bisector report bisector.report.yml.gz
+
+# Show steps with the "test" name or category
+bisector report bisector.report.yml.gz \-\-only test
+
+# Help of a exekall LISA\(aqs step options
+bisector step\-help exekall\-LISA\-test
+
+# Get all information about tests failures
+bisector report bisector.report.yml.gz \-overbose
+
+# Show the tests failure backtraces and messages, and the metrics in the
+# other cases.
+# \-oshow\-details=msg only displays the message without the backtrace
+bisector report bisector.report.yml.gz \-oshow\-details
+
+# Ignore some exceptions in LISA results
+# These exceptions are related to network/ssh issues and are usually not interesting
+bisector report bisector.report.yml.gz \-oignore\-excep=ExceptionPxssh,HostError,TimeoutError
+
+# Only show the results of a specific test case
+# the name is as reported by exekall, so it is best to use * to match the
+# boilerplate prefix.
+# For example \-otestcase=\(aqOneSmallTask:*\(aq will match both
+# "OneSmallTask:test_slack" and "OneSmallTask:test_task_placement".
+bisector report bisector.report.yml.gz \-otestcase=\(aqOneSmallTask:*\(aq
+
+# Only consider iterations 1 to 5, 42 and 56
+# Useful to limit the amount of downloaded result archives
+bisector report bisector.report.yml.gz \-oiterations=1\-5,42,56
+
+# Ignore LISA tests results that are not failures
+# use that to only download the result archives for failed tests.
+bisector report bisector.report.yml.gz \-oignore\-non\-issue
+
+# Download the archives of failed tests and export stdout/sdterr logs to files in
+# the "logs" directory.
+# The hierarchy created is <folder to export to>/<step name>/<iteration number>
+# This will create files for commands output, xUnit files and download the result archives.
+bisector report bisector.report.yml.gz \-oexport\-logs=logs
+
+# "\-oXXXX=YYYY" options can be applied to a specific step instead of all of them using
+# \-o <step name or category>.XXXX=YYYY
+# This command will only show iteration #2 for the eas_behaviour step
+bisector report bisector.report.yml.gz \-oeas_behaviour.iterations=2
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SH REFERENCES
+.IP [1] 5
+\fI\%https://git\-scm.com/docs/git\-bisect#_bisect_run\fP
+.IP [2] 5
+\fI\%https://learnxinyminutes.com/docs/yaml/\fP
+.SH AUTHOR
+ARM-Software
+.SH COPYRIGHT
+2019, ARM-Software
+.\" Generated by docutils manpage writer.
+.
diff --git a/doc/man1/exekall.1 b/doc/man1/exekall.1
new file mode 100644
index 0000000000000000000000000000000000000000..fd431fc0c6f9c7c6dc3ef6f366eb6c694362e7cd
--- /dev/null
+++ b/doc/man1/exekall.1
@@ -0,0 +1,466 @@
+.\" Man page generated from reStructuredText.
+.
+.TH "EXEKALL" "1" "2019" "" "exekall"
+.SH NAME
+exekall \- test runner
+.
+.nr rst2man-indent-level 0
+.
+.de1 rstReportMargin
+\\$1 \\n[an-margin]
+level \\n[rst2man-indent-level]
+level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
+-
+\\n[rst2man-indent0]
+\\n[rst2man-indent1]
+\\n[rst2man-indent2]
+..
+.de1 INDENT
+.\" .rstReportMargin pre:
+. RS \\$1
+. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
+. nr rst2man-indent-level +1
+.\" .rstReportMargin post:
+..
+.de UNINDENT
+. RE
+.\" indent \\n[an-margin]
+.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.nr rst2man-indent-level -1
+.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
+..
+.SH DESCRIPTION
+.sp
+\fBexekall\fP is a python\-based test runner. The expressions it executes are
+discovered from Python PEP 484 parameter and return value annotations.
+.SH OPTIONS
+.SS exekall
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+usage: exekall [\-h] [\-\-debug] {run,merge,compare} ...
+
+Test runner
+
+PATTERNS
+    All patterns are fnmatch pattern, following basic shell globbing syntax.
+    A pattern starting with "!" is used as a negative pattern.
+    
+
+optional arguments:
+  \-h, \-\-help           show this help message and exit
+  \-\-debug              Show complete Python backtrace when exekall crashes.
+
+subcommands:
+  {run,merge,compare}
+
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SS exekall run
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+usage: exekall run [\-h] [\-s ID_PATTERN] [\-\-list]
+                   [\-\-log\-level {debug,info,warn,error,critical}] [\-\-verbose]
+                   [\-\-artifact\-root ARTIFACT_ROOT | \-\-artifact\-dir ARTIFACT_DIR]
+                   [\-\-load\-db LOAD_DB] [\-\-load\-type TYPE_PATTERN]
+                   [\-\-load\-uuid LOAD_UUID | \-\-replay REPLAY]
+                   [\-\-restrict CALLABLE_PATTERN] [\-\-forbid TYPE_PATTERN]
+                   [\-\-allow CALLABLE_PATTERN]
+                   [\-\-goal TYPE_PATTERN | \-\-callable\-goal CALLABLE_PATTERN]
+                   [\-\-sweep CALLABLE_PATTERN PARAM START STOP STEP]
+                   [\-\-template\-scripts SCRIPT_FOLDER] [\-\-adaptor ADAPTOR]
+                   [\-n N] [\-\-share TYPE_PATTERN] [\-\-random\-order]
+                   [\-\-conf CONF] [\-\-inject SERIALIZED_OBJECT_PATH]
+                   PYTHON_SRC [PYTHON_SRC ...]
+
+Run expressions
+
+Note that the adaptor in the customization module is able to add more
+parameters to \(ga\(gaexekall run\(ga\(ga. In order to get the complete set of options,
+please run \(ga\(gaexekall run YOUR_SOURCES \-\-help\(ga\(ga.
+    
+
+positional arguments:
+  PYTHON_SRC            Python modules files. If passed a folder, all contained files
+                        recursively are selected. By default, the current directory is
+                        selected.
+
+optional arguments:
+  \-h, \-\-help            show this help message and exit
+  \-s ID_PATTERN, \-\-select ID_PATTERN
+                        Only run the expressions with an ID matching any of the supplied
+                        filters.
+  \-\-list                List the expressions that will be run without running them.
+  \-\-log\-level {debug,info,warn,error,critical}
+                        Change the default log level of the standard logging module.
+  \-\-verbose, \-v         More verbose output. Can be repeated for even more verbosity. This
+                        only impacts exekall output, \-\-log\-level for more global settings.
+  \-\-artifact\-root ARTIFACT_ROOT
+                        Root folder under which the artifact folders will be created. Defaults
+                        to EXEKALL_ARTIFACT_ROOT env var.
+  \-\-artifact\-dir ARTIFACT_DIR
+                        Folder in which the artifacts will be stored. Defaults to
+                        EXEKALL_ARTIFACT_DIR env var.
+  \-\-load\-db LOAD_DB     Reload a database to use some of its objects. The DB and its artifact
+                        directory will be merged in the produced DB at the end of the
+                        execution, to form a self\-contained artifact directory.
+  \-\-load\-type TYPE_PATTERN
+                        Load the (indirect) instances of the given class from the database
+                        instead of the root objects.
+  \-\-load\-uuid LOAD_UUID
+                        Load the given UUID from the database.
+  \-\-replay REPLAY       Replay the execution of the given UUID, loading as much prerequisite
+                        from the DB as possible.
+  \-\-restrict CALLABLE_PATTERN
+                        Callable names patterns. Types produced by these callables will only
+                        be produced by these (other callables will be excluded).
+  \-\-forbid TYPE_PATTERN
+                        Fully qualified type names patterns. Callable returning these types or
+                        any subclass will not be called.
+  \-\-allow CALLABLE_PATTERN
+                        Allow using callable with a fully qualified name matching these
+                        patterns, even if they have been not selected for various reasons.
+  \-\-goal TYPE_PATTERN   Compute expressions leading to an instance of a class with name
+                        matching this pattern (or a subclass of it).
+  \-\-callable\-goal CALLABLE_PATTERN
+                        Compute expressions ending with a callable which name is matching this
+                        pattern.
+  \-\-sweep CALLABLE_PATTERN PARAM START STOP STEP
+                        Parametric sweep on a function parameter. It needs five fields:
+                            * pattern matching qualified name of the callable
+                            * name of the parameter
+                            * start value
+                            * stop value
+                            * step size.
+  \-\-template\-scripts SCRIPT_FOLDER
+                        Only create the template scripts of the expressions without running
+                        them.
+  \-\-adaptor ADAPTOR     Adaptor to use from the customization module, if there is more than
+                        one to choose from.
+  \-n N                  Run the tests for a number of iterations.
+  \-\-share TYPE_PATTERN  Class name pattern to share between multiple iterations.
+  \-\-random\-order        Run the expressions in a random order, instead of sorting by name.
+  \-\-conf CONF           LISA configuration file. If multiple configurations of a given type
+                        are found, they are merged (last one can override keys in previous
+                        ones)
+  \-\-inject SERIALIZED_OBJECT_PATH
+                        Serialized object to inject when building expressions
+
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SS exekall compare
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+usage: exekall compare [\-h] db db
+
+Compare two DBs produced by exekall run.
+
+Note that the adaptor in the customization module recorded in the database
+is able to add more parameters to \(ga\(gaexekall compare\(ga\(ga. In order to get the
+complete set of options, please run \(ga\(gaexekall compare DB1 DB2 \-\-help\(ga\(ga.
+    
+
+positional arguments:
+  db          DBs created using exekall run to compare.
+
+optional arguments:
+  \-h, \-\-help  show this help message and exit
+
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SH EXECUTING EXPRESSIONS
+.sp
+Expressions are built by scanning the python source code passed to \fBexekall
+run\fP\&. Selecting which expression to execute using \fBexekall run\fP can be
+achieved in several ways:
+.INDENT 0.0
+.INDENT 3.5
+.INDENT 0.0
+.IP \(bu 2
+\fB\-\-select\fP/\fB\-s\fP with a pattern matching an expression ID. Pattern
+prefixed with \fB!\fP can be used to exclude some expressions.
+.IP \(bu 2
+Pointing \fBexekall run\fP at a subset of python source files. Only files
+(directly or indirectly) imported from these python modules will be
+scanned for callables.
+.UNINDENT
+.UNINDENT
+.UNINDENT
+.sp
+Once the expressions are selected, multiple iterations of it can be executed
+using \fB\-n\fP\&. \fB\-\-share TYPE_PATTERN\fP can be used to share part of the expression
+graph between all iterations, to avoid re\-executing some parts of the
+expression. Be aware that all parameters of what is shared will also be shared
+implicitly to keep consistent expressions.
+.sp
+The adaptor found in the customization module of the python sources you are
+using can add extra options to \fBexekall run\fP, which are shown in \fB\-\-help\fP
+only when these sources are specified as well.
+.SH EXPRESSION ENGINE
+.sp
+At the core of \fBexekall\fP is the expression engine. It is in charge of
+building sensible sequences of calls out of python\-level annotations (see PEP
+484), and then executing them. An expression is a graph where each node has
+named \fIparameters\fP that point to other nodes.
+.SS Expression ID
+.sp
+Each expression has an associated ID that is derived from its structure. The rules are:
+.INDENT 0.0
+.INDENT 3.5
+.INDENT 0.0
+.IP 1. 3
+The ID of the first parameter of a given node is prepended to the ID of
+the node, separated with \fB:\fP\&.  The code \fBf(g())\fP has the ID
+\fBg:f\fP\&.
+.IP 2. 3
+The ID of the node is composed of the name of the operator of that node
+(name of a Python callable), followed by a
+parenthesis\-enclosed list of parameters ID, excluding the first
+parameter. The code \fBf(p1=g(), p2=h(k()))\fP has the ID
+\fBg:f(p2=k:h)\fP\&.
+.IP 3. 3
+Expression values can have named tags attached to them. When displaying
+the ID of such a value, the tag would be inserted right after the
+operator name, inside brackets. The value returned by \fBg\fP tagged with a
+tag named \fBmytag\fP with value \fB42\fP would give:
+\fBg[mytag=42]:f(p2=k:h)\fP\&. Note that tags are only relevant when using
+expression values, since the tags are attached to values, not operators.
+.UNINDENT
+.UNINDENT
+.UNINDENT
+.sp
+The first rule allows seamless composition of simple pipeline stages and is
+especially suited to object oriented programming, since the first parameter of
+methods will be \fBself\fP\&.
+.sp
+Tags can be used to add attach some important metadata to the return value of
+an operator, so it can be easily distinguished when taken out of context.
+.SS Sharing subexpressions
+.sp
+When multiple expressions are to be executed, \fBexekall\fP will eliminate common
+subexpressions. That will apply both inside an expression and between different
+expressions. That avoids re\-executing the same operator multiple times if it
+can be reused and if it would have been called with the same parameters. That
+also ensures that referring to a given type for a parameter will give back the
+same object within any given expression. Executing the IDs \fBg:f(p2=g)\fP and
+\fBg:h\fP will translate to an expression graph equivalent to:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+x = g()
+res1 = f(x, p2=x)
+res2 = h(x)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The expression execution engine logs when a given value is computed or reused.
+.SS Execution
+.sp
+Executing an expression means evaluating each node if it has not already been
+evaluated. If an operator is not reusable, it will always be called when a
+value is requested from it, even if some existing values computed with the same
+parameters exist.
+.sp
+Operators are allowed to be generator functions as well. In that case, the
+engine will iterate over the generator, and will execute the downstream
+expressions for each value it provides. Multiple generator functions can be
+chained, leading to a cascade of values for the same expression.
+.sp
+Once an expression has been executed, all its values will get a UUID that can
+be used to uniquely refer to it, and track where it was used in the logs.
+.SH EXPLOITING ARTIFACTS
+.sp
+\fBexekall run\fP produces an artifact folder. The location can be set using
+\fB\-\-artifact\-dir\fP and other options.
+.SS Folder hierarchy
+.sp
+The artifact folder contains the following files:
+.INDENT 0.0
+.INDENT 3.5
+.INDENT 0.0
+.IP \(bu 2
+\fBINFO.log\fP and \fBDEBUG.log\fP contain logs for info and debug levels of the
+\fBlogging\fP standard module. Note that standard output is not included in
+this log, as it does not go through the \fBlogging\fP module
+.IP \(bu 2
+\fBValueDB.pickle.xz\fP contains a serialized objects graph for each
+expression that was executed. The value of each subexpression is included
+if the object was serializable.
+.IP \(bu 2
+\fBBY_UUID\fP contains symlinks named after UUIDs, and pointing to a
+relevant subfolder in the artifacts. That allows quick lookup of the
+artifacts of a given expression if one has its UUID.
+.IP \(bu 2
+A folder for each expression.
+.IP \(bu 2
+Optionally, an \fBORIGIN\fP folder if the artifact folder is the result of
+\fBexekall merge\fP, or \fBexekall run \-\-load\-db\fP\&. It contains the hierarchy
+of each original artifact folder by using folders and symlinks pointing
+inside the artifact folder.
+.UNINDENT
+.UNINDENT
+.UNINDENT
+.sp
+Inside each expression\(aqs folder, there is a folder with the UUID of the
+expression itself. Having that level allows merging artifact folders together
+and avoids conflict in case two different expressions share the same ID.
+.sp
+Inside that folder, the following files can be found:
+.INDENT 0.0
+.INDENT 3.5
+.INDENT 0.0
+.IP \(bu 2
+\fBSTRUCTURE\fP which contains the structure of the expression. Each
+operator is described by its callable name, its return type, and its
+parameters. Parameters are recursively defined the same way. An \fBsvg\fP or
+\fB\&.dot\fP (graphviz) variant may exist as well.
+.IP \(bu 2
+\fBEXPRESSION.py\fP and \fBTEMPLATE_EXPRESSION.py\fP files are executable
+Python script that are equivalent to what was executed by \fBexekall run\fP\&.
+The template one is created before execution and contains some
+placeholders for the sparks. The other one is updated after execution to
+add commented code that reloads any given value from the database. That
+gives the option to the user to not re\-execute some part of the code, but
+load a serialized value instead.
+.IP \(bu 2
+Artifact folders allocated by some operators.
+.UNINDENT
+.UNINDENT
+.UNINDENT
+.SS exekall compare
+.sp
+\fBValueDB.pickle.xz\fP can be compared using \fBexekall compare\fP\&. This will call the
+comparison method of the adaptor that was used when \fBexekall run\fP was
+executed. That function is expected to compare the expression values found in
+the databases, by matching values that have the same ID on both databases.
+.SH ADDING NEW EXPRESSIONS
+.sp
+Since \fBexekall run\fP will discover expressions based on type annotations of
+callable parameters and return value, all that is needed to extend an existing
+package is to write new callables with such annotations. It is possible to use
+a base class in an annotation, in which case the engine will be free to pick
+all the subclasses it can, and produce an expression with each. A dummy example
+would be:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+import abc
+class BaseConf(abc.ABC):
+   @abc.abstractmethod
+   def get_conf(self):
+      pass
+
+class Conf(BaseConf):
+   # By default, callables with an empty parameter list are ignored. They
+   # can be explicitly be used with "exekall run \-\-allow \(aq*Conf\(aq"
+   def __init__(self):
+      self.x = 42
+
+   def get_conf(self):
+      return x
+
+class Stage1:
+   # exekall recognizes classes as a special case: the parameter annotations
+   # are taken from __init__ and the return type is the class
+   def __init__(self, conf:BaseConf):
+      print("building stage1")
+      self.conf = conf
+
+   # first parameter of methods is automatically annotated with the right
+   # class.
+   # "forward\-references are possible by using a string to annotate.
+   def process_method(self) \-> \(aqStage2\(aq:
+      return Stage2(x.conf.x == 42)
+
+class Stage2:
+   def __init__(self, passed):
+      self.passed = passed
+
+def process1(x:Stage1) \-> Stage2:
+   return Stage2(x.conf.x == 42)
+
+def process2(x:Stage1, conf:BaseConf, has_default_val=33) \-> Stage2:
+   return Stage2(x.conf.x == 0)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+From that, \fBexekall run \-\-allow \(aq*Conf\(aq \-\-goal \(aq*Stage2\(aq\fP would infer the
+expressions \fBConf:Stage1:process_method\fP, \fBConf:Stage1:process1\fP and
+\fBConf:Stage1:process2(conf=Conf)\fP\&. The common subexpression \fBConf:Stage1\fP would be
+shared between these two by default.
+.sp
+If a parameter has a default value, its annotation can be omitted. If a
+parameter has both a default value and an annotation, \fBexekall\fP will try to
+provide a value for it, or use the default value if no subexpression has the right
+type.
+.sp
+When an expression is not detected correctly, \fB\-\-verbose\fP/\fB\-v\fP can be used and
+repeated twice to get more information on what callables are being ignored and
+why. Most common issues are:
+.INDENT 0.0
+.INDENT 3.5
+.INDENT 0.0
+.IP \(bu 2
+Partial annotations: all parameters and return values need to be either
+annotated or have a default value.
+.IP \(bu 2
+Abstract Base Classes (see \fBabc.ABC\fP) with missing implementation
+of some attributes.
+.IP \(bu 2
+Cycles in the expression graphs. Considering types as pipeline stages
+helps avoiding cycles in expression graphs when architecturing a module.
+Not all classes need to be considered as such, only the ones that will be
+used in annotations.
+.IP \(bu 2
+Missing "spark", i.e. operator that can provide values without any
+parameter. The adaptor in the customization module usually takes care of
+doing that based on domain\-specific command line options, but some ignored
+callables may be forcefully selected using \fB\-\-allow\fP if needed.
+.IP \(bu 2
+Missing \fBimport\fP chain from the sources given to \fBexekall run\fP to the
+module that defines the callable that is expected to be used. That can be
+solved by adding more \fBimport\fP statements, or simply giving that source
+file directly to \fBexekall run\fP\&.
+.IP \(bu 2
+Wrong goal selected using \fB\-\-goal\fP\&.
+.UNINDENT
+.UNINDENT
+.UNINDENT
+.SH CUSTOMIZING EXEKALL
+.sp
+The behavior of \fBexekall\fP can be customized by subclassing
+\fBexekall.customization.AdaptorBase\fP in a module that must be called
+\fBexekall_customization.py\fP and located in one of the parent packages of the
+modules that are explicitly passed to \fBexekall run\fP\&.  This allows adding
+extra options to \fBexekall run\fP and \fBcompare\fP, tag values in IDs, change the
+set of callables that will be hidden from the ID and define what type is
+considered to provide reusable values by the engine among other things.
+.SH AUTHOR
+ARM-Software
+.SH COPYRIGHT
+2019, ARM-Software
+.\" Generated by docutils manpage writer.
+.
diff --git a/doc/misc_utilities.rst b/doc/misc_utilities.rst
index 86e29dfe475700fa706c0016545ebd92c4b6a1bd..310a9cac2f364a743ea3b97b4fbdc9fbff1fd794 100644
--- a/doc/misc_utilities.rst
+++ b/doc/misc_utilities.rst
@@ -24,3 +24,9 @@ Utilities
 
 .. automodule:: lisa.utils
    :members:
+
+Sphinx documentation
+====================
+
+.. automodule:: lisa.doc.helpers
+   :members:
diff --git a/doc/pedantic_build.sh b/doc/pedantic_build.sh
index 9185d80dc00ff070679ebe14ee3598c0b9f06a00..599ee79d1027ef6d7f8f325ea04d84ac13772e38 100755
--- a/doc/pedantic_build.sh
+++ b/doc/pedantic_build.sh
@@ -17,9 +17,15 @@
 
 #!/bin/bash
 
+ret=0
+
+##############################
+# Build the main documentation
+##############################
+
 # The documentation of those modules causes some issues,
 # be permissive for warnings related to them
-IGNORE_PATTERN="devlib|bart|wa|exekall.engine"
+IGNORE_PATTERN="devlib|bart|wa|docutils.parsers|gi.repository"
 
 make SPHINXOPTS='-n --no-color' html 2>doc_build.log
 log=$(cat doc_build.log)
@@ -40,11 +46,28 @@ else
     echo "Ignored warnings:"
     echo
     echo "$ignored_warns"
-    ret=0
 fi
 
 echo
 echo "Sphinx log:"
 echo
 echo "$log"
+
+echo
+echo "Building man pages"
+echo
+
+#################
+# Build man pages
+#################
+
+docs=(
+    "tools/bisector/doc/man/"
+    "tools/exekall/doc/man/"
+)
+
+for doc in "${docs[@]}"; do
+    sphinx-build "$LISA_HOME/$doc" "$LISA_HOME/doc/man1" -Enab man || ret=2
+done
+
 exit $ret
diff --git a/doc/source/WA-logo-white.svg b/doc/source/WA-logo-white.svg
deleted file mode 100644
index c3d5841eaf7e126de22901543c6fa804867e5c60..0000000000000000000000000000000000000000
--- a/doc/source/WA-logo-white.svg
+++ /dev/null
@@ -1,78 +0,0 @@
-<?xml version="1.0" encoding="UTF-8" standalone="no"?>
-<!-- Created with Inkscape (http://www.inkscape.org/) -->
-
-<svg
-   xmlns:dc="http://purl.org/dc/elements/1.1/"
-   xmlns:cc="http://creativecommons.org/ns#"
-   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
-   xmlns:svg="http://www.w3.org/2000/svg"
-   xmlns="http://www.w3.org/2000/svg"
-   xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
-   xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
-   width="231.99989"
-   height="128.625"
-   id="svg4921"
-   version="1.1"
-   inkscape:version="0.48.4 r9939"
-   sodipodi:docname="WA-logo-black.svg">
-  <defs
-     id="defs4923" />
-  <sodipodi:namedview
-     id="base"
-     pagecolor="#ffffff"
-     bordercolor="#666666"
-     borderopacity="1.0"
-     inkscape:pageopacity="0.0"
-     inkscape:pageshadow="2"
-     inkscape:zoom="0.70000001"
-     inkscape:cx="80.419359"
-     inkscape:cy="149.66406"
-     inkscape:document-units="px"
-     inkscape:current-layer="layer1"
-     showgrid="false"
-     inkscape:window-width="1676"
-     inkscape:window-height="1027"
-     inkscape:window-x="0"
-     inkscape:window-y="19"
-     inkscape:window-maximized="0"
-     fit-margin-top="0"
-     fit-margin-left="0"
-     fit-margin-right="0"
-     fit-margin-bottom="0" />
-  <metadata
-     id="metadata4926">
-    <rdf:RDF>
-      <cc:Work
-         rdf:about="">
-        <dc:format>image/svg+xml</dc:format>
-        <dc:type
-           rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
-        <dc:title></dc:title>
-      </cc:Work>
-    </rdf:RDF>
-  </metadata>
-  <g
-     inkscape:label="Layer 1"
-     inkscape:groupmode="layer"
-     id="layer1"
-     transform="translate(-135.03125,-342.375)">
-    <path
-       style="fill:#ffffff;fill-opacity:1;stroke:none"
-       d="m 239,342.375 0,11.21875 c -5.57308,1.24469 -10.80508,3.40589 -15.5,6.34375 l -8.34375,-8.34375 -15.5625,15.5625 8.28125,8.28125 c -3.25948,5.08895 -5.62899,10.81069 -6.875,16.9375 l -11,0 0,22 11.46875,0 c 1.38373,5.61408 3.71348,10.8741 6.8125,15.5625 l -8.15625,8.1875 15.5625,15.53125 8.46875,-8.46875 c 4.526,2.73972 9.527,4.77468 14.84375,5.96875 l 0,11.21875 14.59375,0 c -4.57581,-6.7196 -7.25,-14.81979 -7.25,-23.5625 0,-5.85191 1.21031,-11.43988 3.375,-16.5 -10.88114,-0.15024 -19.65625,-9.02067 -19.65625,-19.9375 0,-10.66647 8.37245,-19.40354 18.90625,-19.9375 0.3398,-0.0172 0.68717,0 1.03125,0 10.5808,0 19.2466,8.24179 19.90625,18.65625 5.54962,-2.70912 11.78365,-4.25 18.375,-4.25 7.94803,0 15.06896,2.72769 21.71875,6.0625 l 0,-10.53125 -11.03125,0 c -1.13608,-5.58713 -3.20107,-10.85298 -6.03125,-15.59375 l 8.1875,-8.21875 -15.5625,-15.53125 -7.78125,7.78125 C 272.7607,357.45113 267.0827,354.99261 261,353.625 l 0,-11.25 z m 11,46 c -7.73198,0 -14,6.26802 -14,14 0,7.732 6.26802,14 14,14 1.05628,0 2.07311,-0.12204 3.0625,-0.34375 2.84163,-4.38574 6.48859,-8.19762 10.71875,-11.25 C 263.91776,403.99646 264,403.19884 264,402.375 c 0,-7.73198 -6.26801,-14 -14,-14 z m -87.46875,13.25 -11.78125,4.78125 2.4375,6 c -2.7134,1.87299 -5.02951,4.16091 -6.90625,6.75 L 140,416.5 l -4.96875,11.6875 6.21875,2.65625 c -0.64264,3.42961 -0.65982,6.98214 0,10.53125 l -5.875,2.40625 4.75,11.78125 6.15625,-2.5 c 1.95629,2.70525 4.32606,5.00539 7,6.84375 l -2.59375,6.15625 11.6875,4.9375 2.71875,-6.34375 c 3.01575,0.48636 6.11446,0.48088 9.21875,-0.0312 l 2.4375,6 11.78125,-4.75 -2.4375,-6.03125 c 2.70845,-1.87526 5.03044,-4.16169 6.90625,-6.75 l 6.21875,2.625 4.96875,-11.6875 -6.15625,-2.625 c 0.56936,-3.04746 0.64105,-6.22008 0.1875,-9.375 l 6.125,-2.46875 -4.75,-11.78125 -5.90625,2.40625 c -1.8179,-2.74443 -4.05238,-5.13791 -6.59375,-7.0625 L 189.6875,406.9688 178,402.0313 l -2.5,5.84375 c -3.41506,-0.712 -6.97941,-0.8039 -10.53125,-0.21875 z m 165.28125,7.125 -7.09375,19.125 -9.59375,23 -1.875,-42.0625 -14.1875,0 -18.1875,42.0625 -1.78125,-42.0625 -13.8125,0 2.5,57.875 17.28125,0 18.71875,-43.96875 1.9375,43.96875 16.90625,0 0.0312,-0.0625 2.71875,0 1.78125,-5.0625 7.90625,-22.90625 0.0312,0 1.59375,-4.65625 4.46875,-10.40625 7.46875,21.75 -11.125,0 -3.71875,10.75 18.625,0 3.625,10.53125 15,0 -21.4375,-57.875 z m -158,15.875 c 4.48547,0.0706 8.71186,2.76756 10.5,7.1875 2.38422,5.89328 -0.45047,12.61577 -6.34375,15 -5.89327,2.38421 -12.61578,-0.48172 -15,-6.375 -2.3097,-5.70909 0.29002,-12.18323 5.8125,-14.75 0.17811,-0.0828 0.34709,-0.14426 0.53125,-0.21875 1.47332,-0.59605 3.00484,-0.86727 4.5,-0.84375 z m -0.1875,3.40625 c -0.2136,5.4e-4 -0.44162,0.0134 -0.65625,0.0312 -0.79249,0.0658 -1.56779,0.24857 -2.34375,0.5625 -4.13846,1.67427 -6.14302,6.3928 -4.46875,10.53125 1.67428,4.13847 6.3928,6.14301 10.53125,4.46875 4.13847,-1.67428 6.11177,-6.3928 4.4375,-10.53125 -1.27532,-3.15234 -4.29605,-5.07059 -7.5,-5.0625 z"
-       id="rect4081-3-8"
-       inkscape:connector-curvature="0"
-       sodipodi:nodetypes="cccccccccccccccccscscscsccccccccccsssccsscccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccssssccssssssss" />
-    <g
-       id="g3117"
-       transform="translate(-244.99999,-214.64287)">
-      <g
-         transform="translate(83.928571,134.28571)"
-         id="text4037-4-7"
-         style="font-size:79.3801651px;font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:DejaVu Sans;-inkscape-font-specification:DejaVu Sans Bold" />
-      <g
-         transform="translate(83.928571,134.28571)"
-         id="text4041-5-8"
-         style="font-size:79.3801651px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:DejaVu Sans;-inkscape-font-specification:DejaVu Sans" />
-    </g>
-  </g>
-</svg>
diff --git a/doc/trace_analysis.rst b/doc/trace_analysis.rst
index 0eaa6b565c92e82b90deaf2d532725465997e2a2..b36e2e4b55fd05750c6df54e15eb5b2b345a2965 100644
--- a/doc/trace_analysis.rst
+++ b/doc/trace_analysis.rst
@@ -44,7 +44,9 @@ The majority of these dataframes are time-indexed (and if they aren't, it will
 be called out in the docstring). This makes it easy to create dataframe slices
 to study specific trace windows.
 
-.. include:: analysis_df_list.rst
+.. exec::
+    from lisa.doc.helpers import get_analysis_list
+    print(get_analysis_list("df_"))
 
 Plots
 +++++
@@ -54,7 +56,9 @@ they are also saved in the same directory as your ``trace.dat``
 
 .. TODO:: Generate some sample plots using the nosetest trace
 
-.. include:: analysis_plot_list.rst
+.. exec::
+    from lisa.doc.helpers import get_analysis_list
+    print(get_analysis_list("plot_"))
 
 API
 ===
diff --git a/doc/workflows/automated_testing.rst b/doc/workflows/automated_testing.rst
index f574e08a3dfb276be1640b619656eccf399cad7b..b2fda442a40a61abfa2bf685a548b37f0528bfb0 100644
--- a/doc/workflows/automated_testing.rst
+++ b/doc/workflows/automated_testing.rst
@@ -19,6 +19,8 @@ on top of ``exekall``. It efficiently shares as many stages as possible between
 tests to speed up the process, and it records these results in a database for
 later inspection.
 
+.. seealso:: :ref:`exekall main documentation<exekall-doc>`
+
 Running tests
 +++++++++++++
 
@@ -72,26 +74,32 @@ output. At the deepest levels, one can find artifacts useful for failure
 analysis, such as ``trace.dat`` files obtained using ``trace-cmd`` tool, and
 some graphs generated by the tests.
 
-A major artifact is a ``VALUE_DB.pickle.xz`` file. It contains the objects
-returned by every stage of the tests, serialized in Python's Pickle format. The
-``exekall compare`` subcommand can compare two such files, and give a list of
-changes in failure rate. The compared files need to contain multiple iterations
-of the same test to have a useful comparison.  Non-significant
+A major artifact is a ``VALUE_DB.pickle.xz`` file (see
+:class:`exekall.engine.ValueDB`). It contains the objects returned by every
+stage of the tests, serialized in Python's Pickle format. The ``exekall
+compare`` subcommand can compare two such files, and give a list of changes in
+failure rate. The compared files need to contain multiple iterations of the
+same test to have a useful comparison.  Non-significant
 regressions/improvements are not displayed by default. The threshold over which
 the change is considered non-significant can be modified using ``--alpha``,
 which will set the alpha risk of the Fisher's exact test carried out on a
 contingency table like this one:
 
-.. table:: Contingency table for one testcase
+.. list-table:: Contingency table for one testcase
   :widths: auto
   :align: center
-
-  ======   =====  =====
-  count     old    new
-  ======   =====  =====
-  passed   15     80
-  failed   5      20
-  ======   =====  =====
+  :header-rows: 1
+  :stub-columns: 1
+
+  * - count
+    - old
+    - new
+  * - passed
+    - 15
+    - 80
+  * - failed
+    - 5
+    - 20
 
 That would represent an ``old`` test session with 20 iterations of the test, 15
 of which passed and 5 failed. The ``new`` session would have had 100
@@ -219,21 +227,9 @@ bisector
 ========
 
 ``bisector`` allows setting up the steps of a test iteration, repeating
-them an infinite number of times (by default). These steps can involve flashing
-the board, rebooting it, and running a test command. If one step goes wrong,
-bisector implements the logic to retry, abort it, mark it as good or bad
-depending on the type of step used. By now, you may have noticed some
-similarities between ``bisector`` behaviour and what is expected of the command
-executed by ``git bisect run`` [#]_: that is no coincidence, as both ``bisector
-run`` and ``bisector report`` can be used as a ``git bisect run``-compliant
-script.
-
-``bisector run`` records all the output of the steps in a machine-readable
-report that can be inspected using ``bisector report``. The emphasis is put on
-reliability against unexpected interruption, flaky commands and other issues
-that happen on long running sessions. ``bisector`` will never leave you with an
-inconsistent report, or worse, no report at all. A new report is saved after
-each iteration and can be inspected as the execution goes on.
+them an infinite number of times (by default). 
+
+.. seealso:: :ref:`bisector main documentation<bisector-doc>`
 
 .. [#] https://git-scm.com/docs/git-bisect
 
diff --git a/lisa/doc/helpers.py b/lisa/doc/helpers.py
new file mode 100644
index 0000000000000000000000000000000000000000..ae7a7927af654fe3482f776e0b8e0be1df2127e9
--- /dev/null
+++ b/lisa/doc/helpers.py
@@ -0,0 +1,205 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# Copyright (C) 2019, ARM Limited and contributors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"); you may
+# not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+import io
+import contextlib
+import subprocess
+import inspect
+
+from docutils.parsers.rst import Directive, directives
+from docutils.parsers.rst.directives import flag
+from docutils import nodes
+from docutils.statemachine import ViewList
+
+from lisa.analysis.base import TraceAnalysisBase
+from lisa.utils import get_subclasses
+
+class RecursiveDirective(Directive):
+    """
+    Base class helping nested parsing.
+
+    Options:
+
+    * ``literal``: If set, a literal block will be used, otherwise the text
+      will be interpreted as reStructuredText.
+    """
+    option_spec = {
+        'literal': flag,
+    }
+
+    def parse_nested(self, txt, source=None):
+        """
+        Parse text as reStructuredText if the ``literal`` option is not set.
+
+        Otherwise, interpret the text as a line block.
+        """
+        if 'literal' in self.options:
+            node = nodes.literal_block(txt, txt, classes=[])
+            # Avoid syntax highlight
+            node['language'] = 'text'
+            return [node]
+        else:
+            txt = ViewList(txt.splitlines(), source)
+            node = nodes.Element()
+            self.state.nested_parse(txt, self.content_offset, node)
+            return node.children
+
+
+class ExecDirective(RecursiveDirective):
+    """
+    reStructuredText directive to execute the specified python code and insert
+    the output into the document::
+
+        .. exec::
+
+            import sys
+            print(sys.version)
+
+    Options:
+
+    * ``literal``: If set, a literal block will be used, otherwise the text
+      will be interpreted as reStructuredText.
+    """
+    has_content = True
+
+    def run(self):
+        stdout = io.StringIO()
+        code = '\n'.join(self.content)
+        with contextlib.redirect_stdout(stdout):
+            exec(code)
+        out = stdout.getvalue()
+        return self.parse_nested(out)
+
+directives.register_directive('exec', ExecDirective)
+
+
+class RunCommandDirective(RecursiveDirective):
+    """
+    reStructuredText directive to execute the specified command and insert
+    the output into the document::
+
+        .. run-command::
+           :capture-stderr:
+           :ignore-error:
+           :literal:
+
+           exekall --help
+
+    Options:
+
+    * ``literal``: If set, a literal block will be used, otherwise the text
+      will be interpreted as reStructuredText.
+    * ``capture-stderr``: If set, stderr will be captured in addition to stdout.
+    * ``ignore-error``: The return status of the command will be ignored.
+      Otherwise, it will raise an exception and building the
+      documentation will fail.
+    """
+    has_content = True
+    option_spec = {
+        'ignore-error': flag,
+        'capture-stderr': flag,
+        'literal': flag,
+    }
+
+    def run(self):
+        options = self.options
+        if 'capture-stderr' in options:
+            stderr = subprocess.STDOUT
+        else:
+            stderr = None
+
+        check = False if 'ignore-error' in options else True
+
+        cmd = '\n'.join(self.content)
+        out = subprocess.run(
+            cmd, shell=True, check=check,
+            stdout=subprocess.PIPE, stderr=stderr,
+        ).stdout.decode('utf-8')
+
+        return self.parse_nested(out, cmd)
+
+directives.register_directive('run-command', RunCommandDirective)
+
+
+def is_test(method):
+    """
+    Check if a method is a test method.
+    """
+    if not callable(method):
+        return False
+
+    if method.__name__.startswith('test_'):
+        return True
+
+    # Tests are methods with an annotated return type, with at least
+    # one base class with a name containing 'result'
+    try:
+        ret_type = method.__annotations__['return']
+        base_cls_list = inspect.getmro(ret_type)
+    except (AttributeError, KeyError):
+        return False
+    else:
+        return any(
+            'result' in cls.__qualname__.lower()
+            for cls in base_cls_list
+        )
+
+
+def autodoc_process_test_method(app, what, name, obj, options, lines):
+    # Append the list of available test methods for all classes that appear to
+    # have some.
+    if what == 'class':
+        test_list = [
+            member
+            for member_name, member in inspect.getmembers(obj, is_test)
+        ]
+        if test_list:
+            test_list_doc = '\n:Test methods:\n\n{}\n\n'.format('\n'.join(
+                '    * :meth:`~{}`'.format(
+                    method.__module__ + '.' + method.__qualname__
+                )
+                for method in test_list
+            ))
+
+            lines.extend(test_list_doc.splitlines())
+
+
+def autodoc_process_analysis_events(app, what, name, obj, options, lines):
+    # Append the list of required trace events
+    if what != 'method' or not hasattr(obj, "used_events"):
+        return
+
+    events_doc = "\n:Required trace events:\n\n{}\n\n".format(obj.used_events.doc_str())
+    lines.extend(events_doc.splitlines())
+
+
+def get_analysis_list(prefix):
+    rst_list = []
+
+    for subclass in get_subclasses(TraceAnalysisBase):
+        class_path = "{}.{}".format(subclass.__module__, subclass.__qualname__)
+        analysis = subclass.__module__.split(".")[-1]
+        meth_list = [name for name, member in inspect.getmembers(subclass, callable)
+                     if name.startswith(prefix)]
+
+        rst_list += [":class:`{0}<{1}>`::meth:`~{1}.{2}`".format(analysis, class_path, meth)
+                     for meth in meth_list]
+
+    joiner = '\n* '
+    return joiner + joiner.join(rst_list)
+
+# vim :set tabstop=4 shiftwidth=4 expandtab textwidth=80
diff --git a/lisa/doc/manconf.py b/lisa/doc/manconf.py
new file mode 100644
index 0000000000000000000000000000000000000000..c063b9642e8c566e496f67ec7ecf3deafa633cc3
--- /dev/null
+++ b/lisa/doc/manconf.py
@@ -0,0 +1,75 @@
+# -*- coding: utf-8 -*-
+#
+# Configuration file for the Sphinx documentation builder.
+#
+# This file does only contain a selection of the most common options. For a
+# full list see the documentation:
+# http://www.sphinx-doc.org/en/master/config
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+
+# Get the custom reST directives
+import lisa.doc.helpers
+
+# -- Project information -----------------------------------------------------
+
+copyright = '2019, ARM-Software'
+author = 'ARM-Software'
+# Only use the year as the build date in the man page to get stable output
+today_fmt = '%Y'
+
+# -- General configuration ---------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#
+# needs_sphinx = '1.0'
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    'sphinx.ext.todo',
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+#
+# source_suffix = ['.rst', '.md']
+source_suffix = '.rst'
+
+# The master toctree document.
+master_doc = 'man'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = None
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = []
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = None
+
+# -- Extension configuration -------------------------------------------------
+
+# -- Options for todo extension ----------------------------------------------
+
+# If true, `todo` and `todoList` produce output, else they produce nothing.
+todo_include_todos = True
+
diff --git a/lisa/exekall_customize.py b/lisa/exekall_customize.py
index 5f6ed5810e505f9db6176d063d97ff9b0a2327ec..f41d73a1e7dda61143e7f5229c95139a6e1bf871 100644
--- a/lisa/exekall_customize.py
+++ b/lisa/exekall_customize.py
@@ -34,7 +34,7 @@ from lisa.tests.base import TestBundle, ResultBundle
 from lisa.tests.scheduler.load_tracking import InvarianceItem
 from lisa.regression import compute_regressions
 
-from exekall.utils import get_name, get_method_class
+from exekall.utils import get_name, get_method_class, add_argument
 from exekall.engine import ExprData, Consumer, PrebuiltOperator
 from exekall.customization import AdaptorBase
 
@@ -93,7 +93,7 @@ class LISAAdaptor(AdaptorBase):
     def get_non_reusable_type_set(self):
         return {NonReusable}
 
-    def get_prebuilt_set(self):
+    def get_prebuilt_op_set(self):
         non_reusable_type_set = self.get_non_reusable_type_set()
         op_set = set()
 
@@ -194,11 +194,11 @@ class LISAAdaptor(AdaptorBase):
 
     @staticmethod
     def register_run_param(parser):
-        parser.add_argument('--conf', action='append',
+        add_argument(parser, '--conf', action='append',
             default=[],
             help="LISA configuration file. If multiple configurations of a given type are found, they are merged (last one can override keys in previous ones)")
 
-        parser.add_argument('--inject', action='append',
+        add_argument(parser, '--inject', action='append',
             metavar='SERIALIZED_OBJECT_PATH',
             default=[],
             help="Serialized object to inject when building expressions")
@@ -206,19 +206,19 @@ class LISAAdaptor(AdaptorBase):
         # Create an empty TargetConf, so we are able to get the list of tests
         # as if we were going to execute them using a target.
         # note: that is only used for generating the documentation.
-        parser.add_argument('--inject-empty-target-conf', action='store_true',
+        add_argument(parser, '--inject-empty-target-conf', action='store_true',
             help=argparse.SUPPRESS)
 
     @staticmethod
     def register_compare_param(parser):
-        parser.add_argument('--alpha', type=float,
+        add_argument(parser, '--alpha', type=float,
             default=5,
             help="""Alpha risk for Fisher exact test in percents.""")
 
-        parser.add_argument('--non-significant', action='store_true',
+        add_argument(parser, '--non-significant', action='store_true',
             help="""Also show non-significant changes of failure rate.""")
 
-        parser.add_argument('--remove-tag', action='append',
+        add_argument(parser, '--remove-tag', action='append',
             default=[],
             help="""Remove the given tags in the testcase IDs before comparison.""")
 
diff --git a/lisa/regression.py b/lisa/regression.py
index d9e4a92b66dd46f5c51efdfd21044b57f0b74ecd..d247ecb1b8d5728e92efcfe9e9223012840682b9 100644
--- a/lisa/regression.py
+++ b/lisa/regression.py
@@ -182,20 +182,20 @@ class RegressionResult:
 def compute_regressions(old_list, new_list, remove_tags=[], **kwargs):
     """
     Compute a list of :class:`RegressionResult` out of two lists of
-    :class:`exekall.engine.FrozenVal`.
+    :class:`exekall.engine.FrozenExprVal`.
 
     The tests are first grouped by their ID, and then a
     :class:`RegressionResult` is computed for each of these ID.
 
-    :param old_list: old series of :class:`exekall.engine.FrozenVal`.  Values
+    :param old_list: old series of :class:`exekall.engine.FrozenExprVal`.  Values
         with a UUID that is also present in `new_list` will be removed from
         that list before the regressions are computed.
-    :type old_list: list(exekall.engine.FrozenVal)
+    :type old_list: list(exekall.engine.FrozenExprVal)
 
-    :param new_list: new series of :class:`exekall.engine.FrozenVal`. Values
+    :param new_list: new series of :class:`exekall.engine.FrozenExprVal`. Values
         with a UUID that is also present in `old_list` will be removed from
         that list before the regressions are computed.
-    :type new_list: list(exekall.engine.FrozenVal)
+    :type new_list: list(exekall.engine.FrozenExprVal)
 
     :param remove_tags: remove the given list of tags from the IDs before
         computing the regression. That allows computing regressions with a
@@ -216,7 +216,7 @@ def compute_regressions(old_list, new_list, remove_tags=[], **kwargs):
             if froz_val.uuid not in excluded_uuids
         ]
 
-    # Remove from the new_list all the FrozenVal that were carried from the
+    # Remove from the new_list all the FrozenExprVal that were carried from the
     # old_list sequence. That is important since running "exekall run --load-db"
     # will contain both new and old data, so old data needs to be filtered out
     # before we can actually compare the two sets.
diff --git a/shell/lisa_shell b/shell/lisa_shell
index 2a83918b58c96b3a75237829b0bc2ea8f4856fde..9ff930c891300466e29a24a77f70cc251072aa15 100755
--- a/shell/lisa_shell
+++ b/shell/lisa_shell
@@ -45,6 +45,9 @@ export LISA_CONF=${LISA_CONF:-$LISA_HOME/target_conf.yml}
 export LISA_RESULT_ROOT=${LISA_RESULT_ROOT:-$LISA_HOME/results}
 export EXEKALL_ARTIFACT_ROOT=${EXEKALL_ARTIFACT_ROOT:-$LISA_RESULT_ROOT}
 
+# Add our man pages
+export MANPATH="$MANPATH:$LISA_HOME/doc/"
+
 ################################################################################
 # Helpers
 ################################################################################
diff --git a/tools/bisector/bisector/bisector.py b/tools/bisector/bisector/bisector.py
index 700e8b1eafe7a7525724e6300d963afa7e60d323..346275e918826ad983ff78e2f8aea46f37208ae7 100755
--- a/tools/bisector/bisector/bisector.py
+++ b/tools/bisector/bisector/bisector.py
@@ -600,7 +600,7 @@ class _DefaultType:
     When assigning the Default singleton to an attribute, it will:
 
     - Check if the attribute already exists. If yes, its value is retained.
-    - Otherwise, lookup the attribute in the :attr:`attr_init` dict of the class.
+    - Otherwise, lookup the attribute in the ``attr_init`` dict of the class.
 
     This behaviour allows setting a default value to an attribute, without
     overwriting a pre-existing value. Partial reinitialization of deserialized
@@ -629,10 +629,10 @@ class SerializableMeta(type):
     """
     Metaclass for all serializable classes.
 
-    It ensures the class will always have a :attr:`name` and :attr:`cat`
-    attributes, as well as constructing a ChainMap from the :attr:`attr_init`
+    It ensures the class will always have a ``name`` and ``cat``
+    attributes, as well as constructing a ChainMap from the ``attr_init``
     dictionaries of its base classes. That means that usual inheritance rules
-    will apply to the content of :attr:`attr_init` .
+    will apply to the content of ``attr_init`` .
     """
 
     def __init__(self, *args, **kwargs):
@@ -676,7 +676,7 @@ class Serializable(metaclass=SerializableMeta):
     """
     Base class of all serializable classes.
 
-    Subclasses MUST implement a :attr:`yaml_tag` class attribute, in order to
+    Subclasses MUST implement a ``yaml_tag`` class attribute, in order to
     have a stable tag associated with them that can survive accross class
     renames and refactoring.
     """
@@ -723,14 +723,14 @@ class Serializable(metaclass=SerializableMeta):
         Determine what state must be preserved when the instance is serialized.
 
         Attributes with a value equal to the corresponding value in
-        :attr:`attr_init` will not be serialized, since they will be recreated
+        ``attr_init`` will not be serialized, since they will be recreated
         when the instance is deserialized. That limits the number of attributes
         that are actually stored, thereby limiting the scope of backward
         compatibility issues.  It also means that an update to the code could
         change the default value, so the deserialized instance will not
         necessarily be equal to the serialized one.
 
-        Attributes listed in :attr:`dont_save` will not be serialized.
+        Attributes listed in ``dont_save`` will not be serialized.
         """
         cls = type(self)
         attr_init_map = cls.attr_init
@@ -751,8 +751,8 @@ class StepResultBase(Serializable):
     """
     Base class of all step results.
 
-    Step results are returned by the :meth:`run` method of steps.
-    It must implement :attr:`bisect_ret` containing a value of :class:`BisectRet` .
+    Step results are returned by the :meth:`StepBase.run` method of steps.
+    It must implement ``bisect_ret`` containing a value of :class:`BisectRet` .
     """
 
     def filtered_bisect_ret(self, steps_filter=None):
@@ -897,12 +897,14 @@ def write_stdout(txt):
     LOG_FILE.buffer.flush()
 
 def call_process(cmd, *args, merge_stderr=True, **kwargs):
-    """Call a given command with the given arguments and return its standard output.
+    """
+    Call a given command with the given arguments and return its standard
+    output.
 
     :param cmd: name of the command to run
     :param args: command line arguments passed to the command
     :param merge_stderr: merge stderr with stdout.
-    :param kwargs: parameters passed to :meth:`subprocess.check_output`
+    :param kwargs: parameters passed to :func:`subprocess.check_output`
     """
     cmd = tuple(str(arg) for arg in cmd)
     if merge_stderr:
@@ -953,7 +955,7 @@ def get_steps_kwarg_parsers(cls, method_name):
     Analyze a method to extract the parameters with command line parsers.
 
     The parser must be a :class:`Param` so it handles parsing of arguments
-    coming from the command line. It must be specified in the :attr:`options`
+    coming from the command line. It must be specified in the ``options``
     class attribute.
 
     :param method_name: name of the method to analyze
@@ -1004,8 +1006,8 @@ class StepMeta(abc.ABCMeta, type(Serializable)):
     """
     Metaclass of all steps.
 
-    Wraps :meth:`__init__` and :meth:`report` to preprocess the values
-    of the parameters annotated with a command line option parser.
+    Wraps ``__init__()`` and ``report()`` to preprocess the values of the
+    parameters annotated with a command line option parser.
     """
     def __new__(meta_cls, name, bases, dct):
         # Wrap some methods to preprocess some parameters that have a parser
@@ -1107,7 +1109,7 @@ class StepABC(Serializable, metaclass=StepMeta):
         """
         Display the list of results gathered when executing :meth:`run`.
 
-        Keyword-only parameters are supported as for :meth:`__init__`
+        Keyword-only parameters are supported as for ``__init__()``
         """
         pass
 
@@ -1222,7 +1224,7 @@ class StepBase(StepABC):
             if not parser_map:
                 continue
             out(indent + '{}:'.format(pretty))
-            for name, param in parser_map.items():
+            for name, param in sorted(parser_map.items(), key=lambda k_v: k_v[0]):
                 name = name.replace('_', '-')
                 opt_header = indent + '  -o {name}= ({type_desc}) '.format(
                     name = name,
@@ -1240,7 +1242,7 @@ class StepBase(StepABC):
         return out
 
     def _run_cmd(self, i_stack, env=None):
-        """Run :attr:`cmd` command and records the result."""
+        """Run ``cmd`` command and records the result."""
 
         res_list = list()
 
@@ -1710,10 +1712,11 @@ def deprecated_parse_testcase_res(testcase, kind, ignored_except_set):
 
 class ExekallLISATestStep(ShellStep):
     """
-    Execute an exekall LISA test command and collect exekall's ValueDB. Also
-    compress the result directory and record its path. It will also define some
-    environment variables that are expected to be used by the command to be
-    able to locate resources to collect.
+    Execute an exekall LISA test command and collect
+    :class:`exekall.engine.ValueDB`. Also compress the result directory and
+    record its path. It will also define some environment variables that are
+    expected to be used by the command to be able to locate resources to
+    collect.
     """
 
     yaml_tag = '!exekall-LISA-test-step'
@@ -2339,6 +2342,10 @@ class LISATestStep(ShellStep):
     result directory and record its path. It will also define some environment
     variables that are expected to be used by the command to be able to locate
     resources to collect.
+
+    .. deprecated:: 1.0
+        This class is designed for legacy LISA, use
+        :class:`ExekallLISATestStep` for current LISA instead.
     """
 
     yaml_tag = '!LISA-test-step'
@@ -2958,7 +2965,7 @@ def get_class(full_qual_name):
                            for serialization, e.g.:
                            /path/to/mod.py:mymodule.LISA-step
                            Note: the name is not the Python class name, but the
-                           value of the :attr:`name` attribute of the class.
+                           value of the ``name`` attribute of the class.
                            The path to the script can be omitted if the module
                            is directly importable (i.e. in sys.path). The module
                            can be omitted for class names that are already
@@ -4047,7 +4054,7 @@ class Report(Serializable):
         """Save the report to the specified path.
 
         :param path: Used to save the report is not None, otherwise use the
-                     existing :attr:`path` attribute.
+             existing ``path`` attribute.
 
         """
         if path:
@@ -4341,7 +4348,10 @@ def get_dbus_bus():
     return pydbus.SessionBus()
 
 def dbus_variant(v):
-    "Build a :class:`Glib.Variant` instance out of a Python object."
+    """
+    Build a :class:`gi.repository.Glib.Variant` instance out of a Python
+    object.
+    """
     if isinstance(v, str):
         v = GLib.Variant('s', v)
     # Signed 64 bits value for integers.
@@ -4360,8 +4370,8 @@ def dbus_variant(v):
 
 def dbus_variant_dict(dct):
     """
-    Build a dictionary with :class:`GLib.Variant` values, so it can be used to
-    create DBus types a{sv} objects.
+    Build a dictionary with :class:`gi.repository.GLib.Variant` values, so it
+    can be used to create DBus types a{sv} objects.
     """
     return {k: dbus_variant(v) for k, v in dct.items()}
 
@@ -5087,9 +5097,9 @@ def _main(argv):
     global SHOW_TRACEBACK
 
     parser = argparse.ArgumentParser(description="""
-    Git-bisect-compatible command driver.
+    Git-bisect-compatible command sequencer.
 
-    This script allows to run commands with timeout handling in predefined
+    bisector allows to run commands with timeout handling in predefined
     sequences (steps). The output is saved in a report that can be later
     analyzed. The exit status of all steps is merged to obtain a git bisect
     compatible value which is returned. The error code {generic_code} is used
@@ -5134,6 +5144,9 @@ def _main(argv):
     report_parser = subparsers.add_parser('report',
         description="""Analyze a report generated by run command. The exit status
         is suitable for git bisect.
+
+        In most cases, step options (``-o``) will act as filters to ignore
+        parts of the data before computing the overall bisect result.
         """
     )
     edit_parser = subparsers.add_parser('edit',
diff --git a/tools/bisector/doc/README b/tools/bisector/doc/README
new file mode 100644
index 0000000000000000000000000000000000000000..8c5b740b1d2211b62e98590c573d54f42fe653d7
--- /dev/null
+++ b/tools/bisector/doc/README
@@ -0,0 +1,4 @@
+The documentation of bisector is cleanly kept separate from the one of LISA, but
+is not intended to be built on its own ATM. The only part that contains a
+conf.py is the manpage.
+
diff --git a/tools/bisector/doc/api.rst b/tools/bisector/doc/api.rst
new file mode 100644
index 0000000000000000000000000000000000000000..4b6a29dd9552ef4a4642167d77e62023ffaaca73
--- /dev/null
+++ b/tools/bisector/doc/api.rst
@@ -0,0 +1,14 @@
+=================
+API Documentation
+=================
+
+.. warning:: The API is for now considered completely internal and could change
+   at any time
+
+In order to support report edition (``bisector edit``) and more stable
+serialized format, new steps constructors must be written in a similar way to
+exisiting ones.
+
+.. automodule:: bisector.bisector
+   :members:
+
diff --git a/tools/bisector/doc/index.rst b/tools/bisector/doc/index.rst
new file mode 100644
index 0000000000000000000000000000000000000000..b9505573f6df4a25c5b136ffa84ab9ab455567f3
--- /dev/null
+++ b/tools/bisector/doc/index.rst
@@ -0,0 +1,53 @@
+.. LISA documentation master file, created by
+   sphinx-quickstart on Tue Dec 13 14:20:00 2016.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+**********************
+Bisector Documentation
+**********************
+
+Overview
+========
+
+Bisector is a ``git bisect run`` compatible tool used in LISA. Check out the
+project's `Github`__ for some guides to installation and setup.
+
+``bisector`` allows setting up the steps of a test iteration, repeating
+them an infinite number of times (by default). These steps can involve flashing
+the board, rebooting it, and running a test command. If one step goes wrong,
+bisector implements the logic to retry, abort it, mark it as good or bad
+depending on the type of step used. By now, you may have noticed some
+similarities between ``bisector`` behaviour and what is expected of the command
+executed by ``git bisect run`` [#]_: that is no coincidence, as both ``bisector
+run`` and ``bisector report`` can be used as a ``git bisect run``-compliant
+script.
+
+``bisector run`` records all the output of the steps in a machine-readable
+report that can be inspected using ``bisector report``. The emphasis is put on
+reliability against unexpected interruption, flaky commands and other issues
+that happen on long running sessions. ``bisector`` will never leave you with an
+inconsistent report, or worse, no report at all. A new report is saved after
+each iteration and can be inspected as the execution goes on.
+
+__ https://github.com/ARM-software/lisa
+.. [#] https://git-scm.com/docs/git-bisect
+
+Contents
+========
+
+.. toctree::
+   :maxdepth: 2
+
+   man/man
+   api
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
+
+
+
diff --git a/tools/bisector/doc/man/Makefile b/tools/bisector/doc/man/Makefile
new file mode 100644
index 0000000000000000000000000000000000000000..51285967a7d9722c5bdee4f6a81c154a56aa0846
--- /dev/null
+++ b/tools/bisector/doc/man/Makefile
@@ -0,0 +1,19 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
diff --git a/tools/bisector/doc/man/conf.py b/tools/bisector/doc/man/conf.py
new file mode 100644
index 0000000000000000000000000000000000000000..b18bc05a4c8e4aa86fd89ec7238cde5e2a934791
--- /dev/null
+++ b/tools/bisector/doc/man/conf.py
@@ -0,0 +1,39 @@
+# -*- coding: utf-8 -*-
+#
+# Configuration file for the Sphinx documentation builder.
+#
+# This file does only contain a selection of the most common options. For a
+# full list see the documentation:
+# http://www.sphinx-doc.org/en/master/config
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+
+# Base Sphinx configuration for manpages
+from lisa.doc.manconf import *
+
+# -- Project information -----------------------------------------------------
+
+project = 'bisector'
+
+# The short X.Y version
+version = ''
+# The full version, including alpha/beta/rc tags
+release = '1.0'
+
+# -- Options for manual page output ------------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+    (master_doc, 'bisector', 'command sequencer',
+     [author], 1)
+]
+
diff --git a/tools/bisector/doc/man/man.rst b/tools/bisector/doc/man/man.rst
new file mode 100644
index 0000000000000000000000000000000000000000..6c939d53fb9f1baeb2472d2efbee1dfa852c3e35
--- /dev/null
+++ b/tools/bisector/doc/man/man.rst
@@ -0,0 +1,244 @@
+Man page
+========
+
+DESCRIPTION
++++++++++++
+
+``bisector`` is a ``git bisect run`` [#]_ compatible tool used in LISA. Its goal is
+to sequence commands to be repeated an arbitrary number of times and generates
+a report.
+
+For example, ``bisector`` can be used to compile a kernel, flash a board,
+reboot it and run test suite. To achieve that, ``bisector`` runs a sequence of
+steps, and saves a report file containing the result of each step. This step
+sequence is run for a number of iterations, or for a given duration. That
+allows tracking fluctuating bugs by repeating a test process many times.
+
+The steps class can implement any run or report behavior, with the ability to
+take parameters. They also decide what data is saved into the report, and
+their contribution to the overall ``git bisect`` result:
+
+* `good`: the test steps passed
+* `bad`: the test steps failed
+* `untestable`: the build or flash step failed 
+* `abort`: the reboot step failed, and the board is now unusable and requires
+  manual intervention
+* `NA`: the step will not impact the overall result
+
+It is important to note that ``bisector`` step classes usually only invoke a
+user-specified command line tool and will use the return code to decide what
+``git bisect`` result to return. They can also implement more specific result
+reporting, and additional run behaviors.
+
+
+OPTIONS
++++++++
+
+bisector
+--------
+
+.. run-command::
+   :ignore-error:
+   :literal:
+
+   bisector --help
+
+bisector run
+------------
+
+.. run-command::
+   :ignore-error:
+   :literal:
+
+   bisector run --help
+
+bisector report
+---------------
+
+.. run-command::
+   :ignore-error:
+   :literal:
+
+   bisector report --help
+
+bisector step-help
+------------------
+
+Steps-specific options to be used with ``bisector run -o`` and ``bisector report -o``.
+
+.. run-command::
+   :ignore-error:
+   :literal:
+
+   bisector step-help
+
+bisector monitor
+----------------
+
+.. run-command::
+   :ignore-error:
+   :literal:
+
+   bisector monitor --help
+
+bisector monitor-server
+-----------------------
+
+.. run-command::
+   :ignore-error:
+   :literal:
+
+   bisector monitor-server --help
+
+bisector edit
+-------------
+
+.. run-command::
+   :ignore-error:
+   :literal:
+
+   bisector edit --help
+
+CONFIGURATION
++++++++++++++
+
+``bisector run`` is configured using a YAML [#]_ file specified using ``--steps`` that
+defines the steps that will be executed in a loop. Each declared step has a (usually
+unique) name and a class that will influence the way its result is used and its
+options.
+
+The YAML file is structured as following:
+
+.. code-block:: yaml
+
+   # Top-level "steps" key is important as the same file can be used to host other
+   # information.
+   steps:
+      
+      # build step will interpret a non-zero exit status of the command as a
+      # bisect untestable status, and zero exit status as bisect good.
+       -
+         class: BuildStep
+         cmd: make defconfig Image dtbs
+         trials: 1
+
+      # flash step will interpret a non-zero exit status of the command as a
+      # bisect abort, and zero exit status ignored.
+      -
+         class: FlashStep
+         cmd: flash-my-board
+         timeout: 180
+         trials: 5
+
+      # reboot step will interpret a non-zero exit status of the command as a
+      # bisect abort, and zero exit status as bisect good.
+       - 
+         class: reboot
+         timeout: 300
+         trials: 10
+         cmd: reboot-my-board
+
+       # exekall LISA test will interpret a non-zero exit status of the command
+       # as bisect bad, and a zero exit status as bisect good.
+       -
+         class: exekall-LISA-test
+         name: one-small-task
+         # Using systemd-run ensures all child process is killed if the session
+         # is interrupted
+         use-systemd-run: true
+         timeout: 3600
+         cmd: lisa-test 'OneSmallTask*'
+
+All step options can also be specified using ``--options/-o``, which will
+override what is described in the YAML steps configuration.
+
+MONITORING
+++++++++++
+
+``bisector run`` allows some live monitoring by exposing a DBus interface. This
+is used by two subcommands: ``bisector monitor-server`` and ``bisector
+monitor``.
+
+Server
+------
+
+``bisector monitor-server`` acts as a registry of all ``bisector run``
+executing under the same user (DBus session bus). It allows ``bisector
+monitor`` to list active instances and also forwards desktop notifications to
+the desktop environment. The server can be (re)started after ``bisector run``
+if necessary.
+
+Monitor
+-------
+
+``bisector monitor`` allows listing active instances of ``bisector run`` (when
+the server is running), and allows querying various information from them.
+Since the query can be directed to a specific PID, the server is only necessary
+for listing.
+
+EXAMPLES
+++++++++
+
+A typical flow of ``bisector`` looks like that:
+
+.. code-block:: shell
+
+   # Run the steps and generate a report.
+   # systemd-run will be used for all steps by using "-o" without specifying a
+   step name or category.
+   bisector run --desc "description of my report" --steps bisector_steps.yaml --report bisector.report.yml.gz -ouse-systemd-run=yes
+
+   # Later inspection of the report, only looking at the steps that have "test"
+   # name or category.
+   bisector report bisector.report.yml.gz
+    
+   # Show steps with the "test" name or category
+   bisector report bisector.report.yml.gz --only test
+    
+   # Help of a exekall LISA's step options
+   bisector step-help exekall-LISA-test
+    
+   # Get all information about tests failures
+   bisector report bisector.report.yml.gz -overbose
+    
+   # Show the tests failure backtraces and messages, and the metrics in the
+   # other cases.
+   # -oshow-details=msg only displays the message without the backtrace
+   bisector report bisector.report.yml.gz -oshow-details
+    
+   # Ignore some exceptions in LISA results
+   # These exceptions are related to network/ssh issues and are usually not interesting
+   bisector report bisector.report.yml.gz -oignore-excep=ExceptionPxssh,HostError,TimeoutError
+    
+   # Only show the results of a specific test case
+   # the name is as reported by exekall, so it is best to use * to match the
+   # boilerplate prefix.
+   # For example -otestcase='OneSmallTask:*' will match both
+   # "OneSmallTask:test_slack" and "OneSmallTask:test_task_placement".
+   bisector report bisector.report.yml.gz -otestcase='OneSmallTask:*'
+    
+   # Only consider iterations 1 to 5, 42 and 56
+   # Useful to limit the amount of downloaded result archives
+   bisector report bisector.report.yml.gz -oiterations=1-5,42,56
+    
+   # Ignore LISA tests results that are not failures
+   # use that to only download the result archives for failed tests.
+   bisector report bisector.report.yml.gz -oignore-non-issue
+    
+   # Download the archives of failed tests and export stdout/sdterr logs to files in
+   # the "logs" directory.
+   # The hierarchy created is <folder to export to>/<step name>/<iteration number>
+   # This will create files for commands output, xUnit files and download the result archives.
+   bisector report bisector.report.yml.gz -oexport-logs=logs
+    
+   # "-oXXXX=YYYY" options can be applied to a specific step instead of all of them using
+   # -o <step name or category>.XXXX=YYYY
+   # This command will only show iteration #2 for the eas_behaviour step
+   bisector report bisector.report.yml.gz -oeas_behaviour.iterations=2
+
+
+REFERENCES
+++++++++++
+
+.. [#] https://git-scm.com/docs/git-bisect#_bisect_run
+.. [#] https://learnxinyminutes.com/docs/yaml/
diff --git a/tools/exekall/doc/README b/tools/exekall/doc/README
new file mode 100644
index 0000000000000000000000000000000000000000..ecbb1e0b3386dce94c6e5b4f0576a3a00718671e
--- /dev/null
+++ b/tools/exekall/doc/README
@@ -0,0 +1,4 @@
+The documentation of exekall is cleanly kept separate from the one of LISA, but
+is not intended to be built on its own ATM. The only part that contains a
+conf.py is the manpage.
+
diff --git a/tools/exekall/doc/index.rst b/tools/exekall/doc/index.rst
new file mode 100644
index 0000000000000000000000000000000000000000..c3d4d7837e6e58cee50dce3d42ad5e225dba6af9
--- /dev/null
+++ b/tools/exekall/doc/index.rst
@@ -0,0 +1,38 @@
+.. LISA documentation master file, created by
+   sphinx-quickstart on Tue Dec 13 14:20:00 2016.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+*********************
+Exekall Documentation
+*********************
+
+Overview
+========
+
+Exekall is the test runner of LISA. Check out the project's `Github`__ for some
+guides to installation and setup.
+
+``exekall`` runs a set of expressions that are discovered from Python sources,
+allowing to build test suites in a highly modular way.
+
+__ https://github.com/ARM-software/lisa
+
+Contents
+========
+
+.. toctree::
+   :maxdepth: 2
+
+   man/man
+   public_api
+   internal_api
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
+
+
diff --git a/tools/exekall/doc/internal_api.rst b/tools/exekall/doc/internal_api.rst
new file mode 100644
index 0000000000000000000000000000000000000000..c93609295aa00200343b86517d369c47eb6a029f
--- /dev/null
+++ b/tools/exekall/doc/internal_api.rst
@@ -0,0 +1,35 @@
+************
+Internal API
+************
+
+.. warning:: This API is for now considered completely internal and could
+   change at any time, except for items listed in :ref:`public-api`
+
+Engine
+======
+
+.. Since there is nothing actually defined in that module, it is just a
+   reference target for other parts of the doc. It is placed right before
+   exekall.engine so jumping to that reference will lead at the right place.
+   
+.. automodule:: exekall.valuedb
+   :members:
+
+.. automodule:: exekall.engine
+   :members:
+
+Customization
+=============
+
+.. automodule:: exekall.customization
+   :members:
+
+Utils
+=====
+
+.. automodule:: exekall.utils
+   :members:
+
+.. automodule:: exekall._utils
+   :members:
+
diff --git a/tools/exekall/doc/man/Makefile b/tools/exekall/doc/man/Makefile
new file mode 100644
index 0000000000000000000000000000000000000000..51285967a7d9722c5bdee4f6a81c154a56aa0846
--- /dev/null
+++ b/tools/exekall/doc/man/Makefile
@@ -0,0 +1,19 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
diff --git a/tools/exekall/doc/man/conf.py b/tools/exekall/doc/man/conf.py
new file mode 100644
index 0000000000000000000000000000000000000000..9182518af3fa1dd82967adc15d299e1b7056056c
--- /dev/null
+++ b/tools/exekall/doc/man/conf.py
@@ -0,0 +1,39 @@
+# -*- coding: utf-8 -*-
+#
+# Configuration file for the Sphinx documentation builder.
+#
+# This file does only contain a selection of the most common options. For a
+# full list see the documentation:
+# http://www.sphinx-doc.org/en/master/config
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+
+# Base Sphinx configuration for manpages
+from lisa.doc.manconf import *
+
+# -- Project information -----------------------------------------------------
+
+project = 'exekall'
+
+# The short X.Y version
+version = ''
+# The full version, including alpha/beta/rc tags
+release = '1.0'
+
+# -- Options for manual page output ------------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+    (master_doc, 'exekall', 'test runner',
+     [author], 1)
+]
+
diff --git a/tools/exekall/doc/man/man.rst b/tools/exekall/doc/man/man.rst
new file mode 100644
index 0000000000000000000000000000000000000000..9180ca2480f62cc2bf2f006566ab146e02c85fd6
--- /dev/null
+++ b/tools/exekall/doc/man/man.rst
@@ -0,0 +1,277 @@
+Man page
+========
+
+DESCRIPTION
++++++++++++
+
+``exekall`` is a python-based test runner. The expressions it executes are
+discovered from Python PEP 484 parameter and return value annotations.
+
+OPTIONS
++++++++
+
+exekall
+-------
+
+.. run-command::
+   :ignore-error:
+   :literal:
+
+   exekall --help
+
+exekall run
+-----------
+
+.. run-command::
+   :ignore-error:
+   :literal:
+
+   # Give the python sources to exekall to get the LISA options in addition to
+   # the generic ones.
+   exekall run "$LISA_HOME/lisa/tests/" --help
+
+exekall compare
+---------------
+
+.. run-command::
+   :ignore-error:
+   :literal:
+
+   exekall compare --help
+
+
+EXECUTING EXPRESSIONS
++++++++++++++++++++++
+
+Expressions are built by scanning the python source code passed to ``exekall
+run``. Selecting which expression to execute using ``exekall run`` can be
+achieved in several ways:
+
+   * ``--select``/``-s`` with a pattern matching an expression ID. Pattern
+     prefixed with **!** can be used to exclude some expressions.
+   * Pointing ``exekall run`` at a subset of python source files. Only files
+     (directly or indirectly) imported from these python modules will be
+     scanned for callables.
+
+Once the expressions are selected, multiple iterations of it can be executed
+using ``-n``. ``--share TYPE_PATTERN`` can be used to share part of the expression
+graph between all iterations, to avoid re-executing some parts of the
+expression. Be aware that all parameters of what is shared will also be shared
+implicitly to keep consistent expressions.
+
+The adaptor found in the customization module of the python sources you are
+using can add extra options to ``exekall run``, which are shown in ``--help``
+only when these sources are specified as well. 
+
+EXPRESSION ENGINE
++++++++++++++++++
+
+At the core of ``exekall`` is the expression engine. It is in charge of
+building sensible sequences of calls out of python-level annotations (see PEP
+484), and then executing them. An expression is a graph where each node has
+named *parameters* that point to other nodes. 
+
+Expression ID
+-------------
+
+Each expression has an associated ID that is derived from its structure. The rules are:
+
+   1. The ID of the first parameter of a given node is prepended to the ID of
+      the node, separated with **:**.  The code :code:`f(g())` has the ID
+      ``g:f``.
+   2. The ID of the node is composed of the name of the operator of that node
+      (name of a Python callable), followed by a
+      parenthesis-enclosed list of parameters ID, excluding the first
+      parameter. The code :code:`f(p1=g(), p2=h(k()))` has the ID
+      ``g:f(p2=k:h)``. 
+   3. Expression values can have named tags attached to them. When displaying
+      the ID of such a value, the tag would be inserted right after the
+      operator name, inside brackets. The value returned by ``g`` tagged with a
+      tag named ``mytag`` with value ``42`` would give:
+      ``g[mytag=42]:f(p2=k:h)``. Note that tags are only relevant when using
+      expression values, since the tags are attached to values, not operators.
+
+The first rule allows seamless composition of simple pipeline stages and is
+especially suited to object oriented programming, since the first parameter of
+methods will be ``self``.
+
+Tags can be used to add attach some important metadata to the return value of
+an operator, so it can be easily distinguished when taken out of context.
+
+Sharing subexpressions
+----------------------
+
+When multiple expressions are to be executed, ``exekall`` will eliminate common
+subexpressions. That will apply both inside an expression and between different
+expressions. That avoids re-executing the same operator multiple times if it
+can be reused and if it would have been called with the same parameters. That
+also ensures that referring to a given type for a parameter will give back the
+same object within any given expression. Executing the IDs ``g:f(p2=g)`` and
+``g:h`` will translate to an expression graph equivalent to::
+
+   x = g()
+   res1 = f(x, p2=x)
+   res2 = h(x)
+
+The expression execution engine logs when a given value is computed or reused.
+
+Execution
+---------
+
+Executing an expression means evaluating each node if it has not already been
+evaluated. If an operator is not reusable, it will always be called when a
+value is requested from it, even if some existing values computed with the same
+parameters exist.
+
+Operators are allowed to be generator functions as well. In that case, the
+engine will iterate over the generator, and will execute the downstream
+expressions for each value it provides. Multiple generator functions can be
+chained, leading to a cascade of values for the same expression.
+
+Once an expression has been executed, all its values will get a UUID that can
+be used to uniquely refer to it, and track where it was used in the logs.
+
+EXPLOITING ARTIFACTS
+++++++++++++++++++++
+
+``exekall run`` produces an artifact folder. The location can be set using
+``--artifact-dir`` and other options.
+
+Folder hierarchy
+----------------
+
+The artifact folder contains the following files:
+
+   * **INFO.log** and **DEBUG.log** contain logs for info and debug levels of the
+     ``logging`` standard module. Note that standard output is not included in
+     this log, as it does not go through the ``logging`` module
+   * **ValueDB.pickle.xz** contains a serialized objects graph for each
+     expression that was executed. The value of each subexpression is included
+     if the object was serializable.
+   * **BY_UUID** contains symlinks named after UUIDs, and pointing to a
+     relevant subfolder in the artifacts. That allows quick lookup of the
+     artifacts of a given expression if one has its UUID.
+   * A folder for each expression.
+   * Optionally, an **ORIGIN** folder if the artifact folder is the result of
+     **exekall merge**, or **exekall run --load-db**. It contains the hierarchy
+     of each original artifact folder by using folders and symlinks pointing
+     inside the artifact folder.
+
+Inside each expression's folder, there is a folder with the UUID of the
+expression itself. Having that level allows merging artifact folders together
+and avoids conflict in case two different expressions share the same ID.
+
+Inside that folder, the following files can be found:
+   
+   * **STRUCTURE** which contains the structure of the expression. Each
+     operator is described by its callable name, its return type, and its
+     parameters. Parameters are recursively defined the same way. An **svg** or
+     **.dot** (graphviz) variant may exist as well.
+   * **EXPRESSION.py** and **TEMPLATE_EXPRESSION.py** files are executable
+     Python script that are equivalent to what was executed by ``exekall run``.
+     The template one is created before execution and contains some
+     placeholders for the sparks. The other one is updated after execution to
+     add commented code that reloads any given value from the database. That
+     gives the option to the user to not re-execute some part of the code, but
+     load a serialized value instead.
+   * Artifact folders allocated by some operators.
+   
+exekall compare
+---------------
+
+**ValueDB.pickle.xz** can be compared using ``exekall compare``. This will call the
+comparison method of the adaptor that was used when ``exekall run`` was
+executed. That function is expected to compare the expression values found in
+the databases, by matching values that have the same ID on both databases.
+
+ADDING NEW EXPRESSIONS
+++++++++++++++++++++++
+
+Since ``exekall run`` will discover expressions based on type annotations of
+callable parameters and return value, all that is needed to extend an existing
+package is to write new callables with such annotations. It is possible to use
+a base class in an annotation, in which case the engine will be free to pick
+all the subclasses it can, and produce an expression with each. A dummy example
+would be::
+
+   import abc
+   class BaseConf(abc.ABC):
+      @abc.abstractmethod
+      def get_conf(self):
+         pass
+
+   class Conf(BaseConf):
+      # By default, callables with an empty parameter list are ignored. They
+      # can be explicitly be used with "exekall run --allow '*Conf'"
+      def __init__(self):
+         self.x = 42
+
+      def get_conf(self):
+         return x
+
+   class Stage1:
+      # exekall recognizes classes as a special case: the parameter annotations
+      # are taken from __init__ and the return type is the class
+      def __init__(self, conf:BaseConf):
+         print("building stage1")
+         self.conf = conf
+
+      # first parameter of methods is automatically annotated with the right
+      # class.
+      # "forward-references are possible by using a string to annotate.
+      def process_method(self) -> 'Stage2':
+         return Stage2(x.conf.x == 42)
+
+   class Stage2:
+      def __init__(self, passed):
+         self.passed = passed
+
+   def process1(x:Stage1) -> Stage2:
+      return Stage2(x.conf.x == 42)
+
+   def process2(x:Stage1, conf:BaseConf, has_default_val=33) -> Stage2:
+      return Stage2(x.conf.x == 0)
+
+From that, ``exekall run --allow '*Conf' --goal '*Stage2'`` would infer the
+expressions ``Conf:Stage1:process_method``, ``Conf:Stage1:process1`` and
+``Conf:Stage1:process2(conf=Conf)``. The common subexpression ``Conf:Stage1`` would be
+shared between these two by default.
+
+If a parameter has a default value, its annotation can be omitted. If a
+parameter has both a default value and an annotation, ``exekall`` will try to
+provide a value for it, or use the default value if no subexpression has the right
+type.
+
+When an expression is not detected correctly, ``--verbose``/``-v`` can be used and
+repeated twice to get more information on what callables are being ignored and
+why. Most common issues are:
+
+   * Partial annotations: all parameters and return values need to be either
+     annotated or have a default value.
+   * Abstract Base Classes (see :class:`abc.ABC`) with missing implementation
+     of some attributes.
+   * Cycles in the expression graphs. Considering types as pipeline stages
+     helps avoiding cycles in expression graphs when architecturing a module.
+     Not all classes need to be considered as such, only the ones that will be
+     used in annotations.
+   * Missing "spark", i.e. operator that can provide values without any
+     parameter. The adaptor in the customization module usually takes care of
+     doing that based on domain-specific command line options, but some ignored
+     callables may be forcefully selected using ``--allow`` if needed.
+   * Missing ``import`` chain from the sources given to ``exekall run`` to the
+     module that defines the callable that is expected to be used. That can be
+     solved by adding more ``import`` statements, or simply giving that source
+     file directly to ``exekall run``.
+   * Wrong goal selected using ``--goal``.
+
+CUSTOMIZING EXEKALL
++++++++++++++++++++
+
+The behavior of ``exekall`` can be customized by subclassing
+:class:`exekall.customization.AdaptorBase` in a module that must be called
+``exekall_customization.py`` and located in one of the parent packages of the
+modules that are explicitly passed to ``exekall run``.  This allows adding
+extra options to ``exekall run`` and ``compare``, tag values in IDs, change the
+set of callables that will be hidden from the ID and define what type is
+considered to provide reusable values by the engine among other things.
+
diff --git a/tools/exekall/doc/public_api.rst b/tools/exekall/doc/public_api.rst
new file mode 100644
index 0000000000000000000000000000000000000000..142857d62010797ef04a21a0c02fdb61f8954849
--- /dev/null
+++ b/tools/exekall/doc/public_api.rst
@@ -0,0 +1,17 @@
+
+.. _public-api:
+
+**********
+Public API
+**********
+
+The following modules are considered stable and are part of the public API:
+
+   * :mod:`exekall.valuedb`
+
+It includes the following classes:
+
+   * :class:`exekall.engine.ValueDB`
+   * :class:`exekall.engine.FrozenExprVal`
+   * :class:`exekall.engine.PrunedFrozVal`
+   * :class:`exekall.engine.FrozenExprValSeq`
diff --git a/tools/exekall/exekall/_utils.py b/tools/exekall/exekall/_utils.py
index d5c3e2531b6ae72e317edc0667e8f2375af39517..e13bb38244266dffdea2133b892ba9fa60be413c 100644
--- a/tools/exekall/exekall/_utils.py
+++ b/tools/exekall/exekall/_utils.py
@@ -35,11 +35,18 @@ import traceback
 import types
 import uuid
 import glob
+import textwrap
+import argparse
 
 class NotSerializableError(Exception):
     pass
 
-def get_class_from_name(cls_name, module_map=sys.modules):
+def get_class_from_name(cls_name, module_map=None):
+    """
+    Get a class object from its full name (including the module name).
+    """
+    # Avoid argument default value that would be huge in Sphinx doc
+    module_map = module_map if module_map is not None else sys.modules
     possible_mod_set = {
         mod_name
         for mod_name in module_map.keys()
@@ -73,9 +80,16 @@ def _get_class_from_name(cls_name, namespace):
         return obj
 
 def create_uuid():
+    """
+    Creates a UUID.
+    """
     return uuid.uuid4().hex
 
 def get_mro(cls):
+    """
+    Wrapper on top of :func:`inspect.getmro` that recognizes ``None`` as a
+    type (treated like ``type(None)``).
+    """
     if cls is type(None) or cls is None:
         return (type(None), object)
     else:
@@ -83,12 +97,25 @@ def get_mro(cls):
         return inspect.getmro(cls)
 
 def get_method_class(function):
+    """
+    Get the class of a method by analyzing its name.
+    """
     cls_name = function.__qualname__.rsplit('.', 1)[0]
     if '<locals>' in cls_name:
         return None
     return eval(cls_name, function.__globals__)
 
 def get_name(obj, full_qual=True, qual=True):
+    """
+    Get a name for ``obj`` (function or class) that can be used in a generated
+    script.
+
+    :param full_qual: Full name of the object, including its module name.
+    :type full_qual: bool
+
+    :param qual: Qualified name of the object
+    :type qual: bool
+    """
     # full_qual enabled implies qual enabled
     _qual = qual or full_qual
     # qual disabled implies full_qual disabled
@@ -124,12 +151,25 @@ def get_name(obj, full_qual=True, qual=True):
     return module_name + name
 
 def get_toplevel_module(obj):
+    """
+    Return the outermost module object in which ``obj`` is defined as a tuple
+    of source file path and line number.
+
+    This is usually a package.
+    """
     module = inspect.getmodule(obj)
     toplevel_module_name = module.__name__.split('.')[0]
     toplevel_module = sys.modules[toplevel_module_name]
     return toplevel_module
 
 def get_src_loc(obj, shorten=True):
+    """
+    Get the source code location of ``obj``
+
+    :param shorten: Shorten the paths of the source files by only keeping the
+        part relative to the top-level package.
+    :type shorten: bool
+    """
     try:
         src_line = inspect.getsourcelines(obj)[1]
         src_file = inspect.getsourcefile(obj)
@@ -174,17 +214,25 @@ def is_serializable(obj, raise_excep=False):
     else:
         return True
 
-# Call the given function at most once per set of parameters
 def once(callable_):
+    """
+    Call the given function at most once per set of parameters
+    """
     return functools.lru_cache(maxsize=None, typed=True)(callable_)
 
 def remove_indices(iterable, ignored_indices):
+    """
+    Filter the given ``iterable`` by removing listed in ``ignored_indices``.
+    """
     return [v for i, v in enumerate(iterable) if i not in ignored_indices]
 
-# Basic reimplementation of typing.get_type_hints for Python versions that
-# do not have a typing module available, and also avoids creating Optional[]
-# when the parameter has a None default value.
 def resolve_annotations(annotations, module_vars):
+    """
+    Basic reimplementation of typing.get_type_hints.
+
+    Some Python versions do not have a typing module available, and it also
+    avoids creating ``Optional[]`` when the parameter has a None default value.
+    """
     return {
         # If we get a string, evaluate it in the global namespace of the
         # module in which the callable was defined
@@ -193,6 +241,9 @@ def resolve_annotations(annotations, module_vars):
     }
 
 def get_module_basename(path):
+    """
+    Get the module name of the module defined in source ``path``.
+    """
     path = pathlib.Path(path)
     module_name = inspect.getmodulename(str(path))
     # This is either garbage or a package
@@ -201,6 +252,15 @@ def get_module_basename(path):
     return module_name
 
 def iterate_cb(iterator, pre_hook=None, post_hook=None):
+    """
+    Iterate over ``iterator``, and  call some callbacks.
+
+    :param pre_hook: Callback called right before getting a new value.
+    :type pre_hook: collections.abc.Callable
+
+    :param post_hook: Callback called right after getting a new value.
+    :type post_hook: collections.abc.Callable
+    """
     with contextlib.suppress(StopIteration):
         for i in itertools.count():
             # Do not execute pre_hook on the first iteration
@@ -213,14 +273,29 @@ def iterate_cb(iterator, pre_hook=None, post_hook=None):
             yield val
 
 def format_exception(e):
+    """
+    Format the traceback of the exception ``e`` in a string.
+    """
     elements = traceback.format_exception(type(e), e, e.__traceback__)
     return ''.join(elements)
 
 
 # Logging level above CRITICAL that is always displayed and used for output
 LOGGING_OUT_LEVEL = 60
+"""
+Log level used for the ``OUT`` level.
+
+This allows sending all the output through the logging module instead of using
+:func:`print`, so it can easily be recorded to a file
+"""
 
 class ExekallFormatter(logging.Formatter):
+    """
+    Custom :class:`logging.Formatter` that takes care of ``OUT`` level.
+
+    This ``OUT`` level allows using :mod:`logging` instead of :func:`print` so
+    it can be redirected to a file easily.
+    """
     def __init__(self, fmt, *args, **kwargs):
         self.default_fmt = logging.Formatter(fmt, *args, **kwargs)
         self.out_fmt = logging.Formatter('%(message)s', *args, **kwargs)
@@ -234,6 +309,24 @@ class ExekallFormatter(logging.Formatter):
             return self.default_fmt.format(record)
 
 def setup_logging(log_level, debug_log_file=None, info_log_file=None, verbose=0):
+    """
+    Setup the :mod:`logging` module.
+
+    :param log_level: Lowest log level name to display.
+    :type log_level: str
+
+    :param debug_log_file: Path to a file where logs are collected at the
+        ``DEBUG`` level.
+    :type debug_log_file: str
+
+    :param info_log_file: Path to a file where logs are collected at the
+        ``INFO`` level.
+    :type info_log_file: str
+
+    :param verbose: Verbosity level. The format string for log entries will
+        contain more information when the level increases.`
+    :type verbose: int
+    """
     logging.addLevelName(LOGGING_OUT_LEVEL, 'OUT')
     level=getattr(logging, log_level.upper())
 
@@ -268,6 +361,11 @@ def setup_logging(log_level, debug_log_file=None, info_log_file=None, verbose=0)
 EXEKALL_LOGGER  = logging.getLogger('EXEKALL')
 
 def out(msg):
+    """
+    To be used as a replacement of :func:`print`.
+
+    This allows easy redirection of the output to a file.
+    """
     EXEKALL_LOGGER.log(LOGGING_OUT_LEVEL, msg)
 
 def info(msg):
@@ -333,6 +431,13 @@ def infer_mod_name(python_src):
     return module_name
 
 def find_customization_module_set(module_set):
+    """
+    Find all customization modules, where subclasses of
+    :class:`exekall.customization.AdaptorBase` are expected to be found.
+
+    It looks for modules named ``exekall_customize`` present in any enclosing
+    package of modules in ``module_set``.
+    """
     def build_full_names(l_l):
         """Explode list of lists, and build full package names."""
         for l in l_l:
@@ -373,6 +478,11 @@ def find_customization_module_set(module_set):
     return customization_module_set
 
 def import_paths(paths):
+    """
+    Import the modules in the given list of paths.
+
+    If a folder is passed, all Python sources are recursively imported.
+    """
     def import_it(path):
         # Recursively import all modules when passed folders
         if path.is_dir():
@@ -388,6 +498,21 @@ def import_paths(paths):
     ))
 
 def import_file(python_src, module_name=None, is_package=False):
+    """
+    Import a module.
+
+    :param python_src: Path to a Python source file.
+    :type python_src: str or pathlib.Path
+
+    :param module_name: Name under which to import the module. If ``None``, the
+        name is inferred using :func:`infer_mod_name`
+    :type module_name: str
+
+    :param is_package: ``True`` if the module is a package. If a folder or
+        ``__init__.py`` is passed, this is forcefully set to ``True``.
+    :type is_package: bool
+
+    """
     python_src = pathlib.Path(python_src).resolve()
 
     # Directly importing __init__.py does not really make much sense and may
@@ -459,6 +584,9 @@ def import_file(python_src, module_name=None, is_package=False):
     return module
 
 def flatten_seq(seq, levels=1):
+    """
+    Flatten a nested sequence, up to ``levels`` levels.
+    """
     if levels == 0:
         return seq
     else:
@@ -466,11 +594,20 @@ def flatten_seq(seq, levels=1):
         return flatten_seq(seq, levels=levels - 1)
 
 def take_first(iterable):
+    """
+    Pick the first item of ``iterable``.
+    """
     for i in iterable:
         return i
     return NoValue
 
 class _NoValueType:
+    """
+    Type of the :attr:`NoValue` singleton.
+
+    This is mostly used like ``None``, in places where ``None`` may be an
+    acceptable value.
+    """
     # Use a singleton pattern to make sure that even deserialized instances
     # will be the same object
     def __new__(cls):
@@ -497,6 +634,9 @@ class _NoValueType:
         return type(self) is type(other)
 
 NoValue = _NoValueType()
+"""
+Singleton with similar purposes as ``None``.
+"""
 
 
 class RestartableIter:
@@ -528,6 +668,19 @@ class RestartableIter:
 
 
 def get_froz_val_set_set(db, uuid_seq=None, type_pattern_seq=None):
+    """
+    Get a set of sets of :class:`exekall.engine.FrozenExprVal`.
+
+    :param db: :class:`exekall.engine.ValueDB` to look into
+    :type db: exekall.engine.ValueDB
+
+    :param uuid_seq: Sequence of UUIDs to select.
+    :type uuid_seq: list(str)
+
+    :param type_pattern_seq: Sequence of :func:`fnmatch.fnmatch` patterns
+        matching type names (including module name).
+    :type type_pattern_seq: list(str)
+    """
 
     def uuid_predicate(froz_val):
         return froz_val.uuid in uuid_seq
@@ -551,7 +704,9 @@ def get_froz_val_set_set(db, uuid_seq=None, type_pattern_seq=None):
     return db.get_by_predicate(predicate, flatten=False, deduplicate=True)
 
 def match_base_cls(cls, pattern_list):
-    # Match on the name of the class of the object and all its base classes
+    """
+    Match the name of the class of the object and all its base classes.
+    """
     for base_cls in get_mro(cls):
         base_cls_name = get_name(base_cls, full_qual=True)
         if not base_cls_name:
@@ -562,6 +717,11 @@ def match_base_cls(cls, pattern_list):
     return False
 
 def match_name(name, pattern_list):
+    """
+    Return ``True`` if ``name`` is matched by any pattern in ``pattern_list``.
+
+    If a pattern starts with ``!``, it is taken as a negative pattern.
+    """
     if name is None:
         return False
 
@@ -596,6 +756,9 @@ def match_name(name, pattern_list):
     return (check(pos_patterns, identity) and check(neg_patterns, invert))
 
 def get_common_base(cls_list):
+    """
+    Get the most derived common base class of classes in ``cls_list``.
+    """
     # MRO in which "object" will appear first
     def rev_mro(cls):
         return reversed(inspect.getmro(cls))
@@ -613,15 +776,19 @@ def get_common_base(cls_list):
     return functools.reduce(common, cls_list)
 
 def get_subclasses(cls):
+    """
+    Get all the (direct and indirect) subclasses of ``cls``.
+    """
     subcls_set = {cls}
     for subcls in cls.__subclasses__():
         subcls_set.update(get_subclasses(subcls))
     return subcls_set
 
 def get_recursive_module_set(module_set, package_set):
-    """Retrieve the set of all modules recurisvely imported from the modules in
-    `module_set`, if they are (indirectly) part of one of the packages named in
-    `package_set`.
+    """
+    Retrieve the set of all modules recursively imported from the modules in
+    ``module_set`` if they are (indirectly) part of one of the packages named
+    in ``package_set``.
     """
 
     recursive_module_set = set()
@@ -655,7 +822,7 @@ def disable_gc():
     Context manager to disable garbage collection.
 
     This can result in significant speed-up in code creating a lot of objects,
-    like ``pickle.load()``.
+    like :func:`pickle.load`.
     """
     if not gc.isenabled():
         yield
@@ -668,7 +835,16 @@ def disable_gc():
         gc.enable()
 
 def render_graphviz(expr):
-    graphviz = expr.get_structure(graphviz=True)
+    """
+    Render the structure of an expression as a graphviz description or SVG.
+
+    :returns: A tuple(bool, content) where the boolean is ``True`` if SVG could
+        be rendered or ``False`` if it still a graphviz description.
+
+    :param expr: Expression to render
+    :type expr: exekall.engine.ExpressionBase
+    """
+    graphviz = expr.format_structure(graphviz=True)
     with tempfile.NamedTemporaryFile('wt') as f:
         f.write(graphviz)
         f.flush()
@@ -686,3 +862,16 @@ def render_graphviz(expr):
             return (True, svg)
 
         return (False, graphviz)
+
+def add_argument(parser, *args, help, **kwargs):
+    """
+    Equivalent to :meth:`argparse.ArgumentParser.add_argument`, with ``help``
+    formatting.
+
+    This allows using parsers setup using raw formatters.
+    """
+    if help is not argparse.SUPPRESS:
+        help=textwrap.dedent(help)
+        # Preserve all new lines where there are, and only wrap the other lines.
+        help='\n'.join(textwrap.fill(line) for line in help.splitlines())
+    return parser.add_argument(*args, **kwargs, help=help)
diff --git a/tools/exekall/exekall/customization.py b/tools/exekall/exekall/customization.py
index e9899b2c10fbebf1fe9a1bd29f6022888d5451ff..343a47f37eaed1acff261573e07fc30c5b692964 100644
--- a/tools/exekall/exekall/customization.py
+++ b/tools/exekall/exekall/customization.py
@@ -22,28 +22,56 @@ from exekall.engine import ValueDB
 from exekall.utils import out, get_name, NoValue, get_subclasses
 
 class AdaptorBase:
+    """
+    Base class of all adaptors.
+
+    :param args: Command line argument namespace as returned by
+        :meth:`argparse.ArgumentParser.parse_args`. Depending on the subcommand
+        used, it could be the arguments of ``exekall run`` or ``exekall
+        compare`` (or any other subcommand).
+    :type args: argparse.Namespace
+
+    An adaptor is a class providing a number of hooks to customize the
+    behaviour of exekall on a given codebase. It should be implemented in a
+    module called ``exekall_customize`` in order to be found by ``exekall
+    run``.
+    """
     name = 'default'
 
-    def __init__(self, args=None):
-        if args is None:
-            args = dict()
+    def __init__(self, args):
         self.args = args
 
     def get_non_reusable_type_set(self):
+        """
+        Return a set of non-reusable types.
+
+        Defaults to an empty set.
+        """
         return set()
 
     @staticmethod
     def get_tags(value):
+        """
+        Returns a dictionnary of tag names to their value.
+
+        Default to empty set of tags, unless value is a :class:`numbers.Number`
+        in which case the value of the number is used.
+        """
         if isinstance(value, numbers.Number):
             tags = {'': value}
         else:
             tags = {}
         return tags
 
-    def update_expr_data(self, expr_data):
-        return
-
     def filter_op_set(self, op_set):
+        """
+        Returns a potentially filtered set of :class:`exekall.engine.Operator`.
+
+        This allows removing some operators from the ones that will be used to
+        build expressions. Defaults to filtering out operators without any
+        parameter, since the "spark" values are usually introduced by the
+        adaptor directly, instead of calling functions from the code base.
+        """
         return {
             op for op in op_set
             # Only select operators with non-empty parameter list. This
@@ -53,44 +81,110 @@ class AdaptorBase:
         }
 
     def format_expr_list(self, expr_list, verbose=0):
+        """
+        Return a string that is printed right after the list of executed
+        expressions.
+
+        :param expr_list: List of :class:`exekall.engine.ExpressionBase` that
+            will be executed. Note that this list has not yet undergone CSE,
+            cloning for multiple iterations or other transformations.
+        :type expr_list: list(exekall.engine.ExpressionBase)
+
+        This can be used to add some information about the expressions that are
+        about to be executed.
+        """
         return ''
 
-    def get_prebuilt_set(self):
+    def get_prebuilt_op_set(self):
+        """
+        Returns a set of :class:`exekall.engine.PrebuiltOperator`.
+
+        This allows injecting any "spark" value that is needed to build the
+        expressions, like configuration objects. These values are usually built
+        out of the custom CLI parameters added by the adaptor.
+        """
         return set()
 
     def get_hidden_op_set(self, op_set):
+        """
+        Returns the set of hidden :class:`exekall.engine.Operator`.
+
+        This allows hiding parts of the IDs that would not add much information
+        but clutter them.
+        """
         self.hidden_op_set = set()
         return self.hidden_op_set
 
     @staticmethod
     def register_run_param(parser):
+        """
+        Register CLI parameters for the ``run`` subcommand.
+
+        :param parser: Parser of the ``run`` subcommand to add arguments onto.
+        :type parser: argparse.ArgumentParser
+        """
         pass
 
     @staticmethod
     def register_compare_param(parser):
+        """
+        Register CLI parameters for the ``compare`` subcommand.
+
+        :param parser: Parser of the ``compare`` subcommand to add arguments onto.
+        :type parser: argparse.ArgumentParser
+        """
         pass
 
     def compare_db_list(self, db_list):
+        """
+        Compare databases listed in ``db_list``.
+
+        :param db_list: List of :class:`exekall.engine.ValueDB` to compare.
+        :type db_list: list(exekall.engine.ValueDB)
+
+        This is called by ``exekall compare`` to actually do something useful.
+        """
         pass
 
     @staticmethod
     def get_default_type_goal_pattern_set():
+        """
+        Returns a set of patterns that will be used as the default value for
+        ``exekall run --goal``.
+        """
         return {'*Result'}
 
-    def resolve_cls_name(self, goal):
-        return utils.get_class_from_name(goal)
-
     @classmethod
     def reload_db(cls, db, path=None):
+        """
+        Hook called when reloading a serialized
+        :class:`exekall.engine.ValueDB`. The returned database will be used.
+
+        :param db: :class:`exekall.engine.ValueDB` that has just been
+            deserialized.
+        :type db: exekall.engine.ValueDB
+
+        :param path: Path of the file of the serialized database if available.
+        :type path: str or None
+        """
         return db
 
     def finalize_expr(self, expr):
+        """
+        Finalize an :class:`exekall.engine.ComputableExpression` right after
+        all its values have been computed.
+        """
         pass
 
-    def result_str(self, result):
-        val = result.value
+    def format_result(self, expr_val):
+        """
+        Format an :class:`exekall.engine.ExprVal` that is the result of an
+        expression. It should return a (short) string that will be displayed at
+        the end of the computation.
+        """
+        val = expr_val.value
         if val is NoValue or val is None:
-            for failed_parent in result.get_excep():
+            for failed_parent in expr_val.get_excep():
                 excep = failed_parent.excep
                 return 'EXCEPTION ({type}): {msg}'.format(
                     type = get_name(type(excep), full_qual=False),
@@ -101,6 +195,14 @@ class AdaptorBase:
             return str(val)
 
     def get_summary(self, result_map):
+        """
+        Return the summary of an ``exekall run`` session as a string.
+
+        :param result_map: Dictionary of expressions to the list of their
+            values.
+        :type result_map: dict(exekall.engine.ComputableExpression,
+            exekall.engine.ExprVal)
+        """
         hidden_callable_set = {
             op.callable_
             for op in self.hidden_op_set
@@ -122,7 +224,7 @@ class AdaptorBase:
         summary = []
         for expr, result_list in result_map.items():
             for result in result_list:
-                msg = self.result_str(result)
+                msg = self.format_result(result)
                 msg = msg + '\n' if '\n' in msg else msg
                 summary.append('{id:<{max_id_len}} {result}'.format(
                     id=result_id_map[result],
@@ -133,6 +235,11 @@ class AdaptorBase:
 
     @classmethod
     def get_adaptor_cls(cls, name=None):
+        """
+        Return the adaptor class that has the name ``name``.
+
+        .. note:: This is not intended to be overriden by subclasses.
+        """
         subcls_list = list(get_subclasses(cls) - {cls})
         if not name:
             if len(subcls_list) > 1:
diff --git a/tools/exekall/exekall/engine.py b/tools/exekall/exekall/engine.py
index 9975a691d8b9261cb6d73f287608607188cb8ae7..7290b74afd1371a3de81193d93b57d89024a32f7 100644
--- a/tools/exekall/exekall/engine.py
+++ b/tools/exekall/exekall/engine.py
@@ -33,9 +33,16 @@ import exekall._utils as utils
 from exekall._utils import NoValue
 
 class NoOperatorError(Exception):
+    """
+    Exception raised when no operator has been found to build objects of a
+    needed type.
+    """
     pass
 
 class IndentationManager:
+    """
+    Manage the indentation level in a generated script.
+    """
     def __init__(self, style):
         self.style = style
         self.level = 0
@@ -50,6 +57,27 @@ class IndentationManager:
         return str(self.style) * self.level
 
 class ValueDB:
+    """
+    Serializable object that contains a graph of :class:`FrozenExprVal`.
+
+    This allows storing all the objects computed for each subexpression that
+    was executed for later inspection.
+
+    :param froz_val_seq_list: List of :class:`FrozenExprValSeq` to store at the
+        root of the database.
+    :type froz_val_seq_list: list(FrozenExprValSeq)
+
+    :param adaptor_cls: A subclass of
+        :class:`exekall.customization.AdaptorBase` that was used when setting
+        up the expressions. This class can provide hooks that are called when
+        deserializing the database.
+    :type adaptor_cls: type
+
+
+    The values of each expression is recorded in a root list of
+    :class:`FrozenExprValSeq`.
+
+    """
     # Version 4 is available since Python 3.4 and improves a bit loading and
     # dumping speed.
     PICKLE_PROTOCOL = 4
@@ -112,6 +140,14 @@ class ValueDB:
 
     @classmethod
     def merge(cls, db_list):
+        """
+        Merge multiple databases together.
+
+        When two different :class:`FrozenExprVal` are available for a given
+        UUID, the one that contains the most information will be selected.
+        This allows natural removal of values created using an
+        :class:`PrebuiltOperator` when the original object is also available.
+        """
         db_list = list(db_list)
         adaptor_cls_set = {
             db.adaptor_cls
@@ -129,6 +165,22 @@ class ValueDB:
 
     @classmethod
     def from_path(cls, path, relative_to=None):
+        """
+        Deserialize a :class:`ValueDB` from a file.
+
+        At the moment, it is assumed to be an LZMA compressed Pickle file.
+
+        :param path: Path to the file containing the serialized
+            :class:`ValueDB`.
+        :type path: str or pathlib.Path
+
+        :param relative_to: If provided, ``path`` is interpreted as being
+            relative to that folder, or to the containing folder if it is a
+            file. This is mainly used to ease generation of scripts that can
+            provide ``relative_to=__file__`` so that the artifact folder can be
+            moved around easily.
+        :type relative_to: str or pathlib.Path
+        """
         if relative_to is not None:
             relative_to = pathlib.Path(relative_to).resolve()
             if not relative_to.is_dir():
@@ -161,6 +213,9 @@ class ValueDB:
         return db
 
     def __reduce_ex__(self, protocol):
+        """
+        Provide custom serialization that will call the adaptor's hooks.
+        """
         return (self._reload_serialized, (self.__dict__,))
 
     @staticmethod
@@ -178,7 +233,8 @@ class ValueDB:
         :type path: pathlib.Path or str
 
         :param optimize: Optimize the representation of the DB. This may
-            increase the dump time, but should speed-up loading/file size.
+            increase the dump time and memory consumption, but should speed-up
+            loading/file size.
         :type optimize: bool
         """
         if optimize:
@@ -230,11 +286,18 @@ class ValueDB:
         return updated_froz_val
 
     def get_by_uuid(self, uuid):
+        """
+        Get a :class:`FrozenExprVal` by its UUID.
+        """
         return self._uuid_map[uuid]
 
     def get_by_predicate(self, predicate, flatten=True, deduplicate=False):
         """
-        Get objects matching the predicate.
+        Get :class:`FrozenExprVal` matching the predicate.
+
+        :param predicate: Predicate callable called with an instance of
+            :class:`FrozenExprVal`. If it returns True, the value is selected.
+        :type predicate: collections.abc.Callable
 
         :param flatten: If False, return a set of frozenset of objects.
             There is a frozenset set for each expression result that shared
@@ -282,6 +345,18 @@ class ValueDB:
             return froz_val_set_set
 
     def get_roots(self, flatten=True):
+        """
+        Get all the root :class:`FrozenExprVal`.
+
+        :param flatten: If True, a set of :class:`FrozenExprVal` is returned,
+            otherwise a set of frozensets of :class:`FrozenExprVal` is returned.
+            Each set will correspond to an expression, and values inside the
+            frozenset will correspond to the values of that expression.
+        :type flatten: bool
+
+        Root values are the result of full expression (as opposed to
+        subexpressions).
+        """
         froz_val_set_set = {
             frozenset(froz_val_seq)
             for froz_val_seq in self.froz_val_seq_list
@@ -292,6 +367,17 @@ class ValueDB:
             return froz_val_set_set
 
     def prune_by_predicate(self, predicate):
+        """
+        Create a new :class:`ValueDB` with all :class:`FrozenExprVal` matching
+        the predicate replaced by a terminal :class:`PrunedFrozVal`.
+
+        :param predicate: Predicate callable called with an instance of
+            :class:`FrozenExprVal`. If it returns True, the value is pruned out.
+        :type predicate: collections.abc.Callable
+
+        This allows trimming a :class:`ValueDB` to a smaller size by removing
+        non-necessary content.
+        """
         def prune(froz_val):
             if isinstance(froz_val, PrunedFrozVal):
                 return froz_val
@@ -336,26 +422,81 @@ class ValueDB:
         )
 
     def get_all(self, **kwargs):
+        """
+        Get all :class:`FrozenExprVal` contained in this database.
+
+        :param kwargs: Keyword arguments forwarded to
+            :meth:`ValueDB.get_by_predicate`
+        :type kwargs: dict
+        """
         return self.get_by_predicate(lambda froz_val: True, **kwargs)
 
     def get_by_type(self, cls, include_subclasses=True, **kwargs):
+        """
+        Get all :class:`FrozenExprVal` contained in this database which value
+        has the specified type.
+
+        :param cls: Class to match.
+        :type cls: type
+
+        :param include_subclasses: If True, the check is done using
+            ``isinstance``, otherwise an exact type check is done using ``is``.
+        :type include_subclasses: bool
+
+        :param kwargs: Keyword arguments forwarded to
+            :meth:`ValueDB.get_by_predicate`
+        :type kwargs: dict
+
+        .. note:: If a subexpressions had a :class:`exekall._utils.NoValue`
+            value, it will not be selected as type matching is done on the
+            value itself, not the return type of the callable used for that sub
+            expression.
+        """
         if include_subclasses:
             predicate = lambda froz_val: isinstance(froz_val.value, cls)
         else:
             predicate = lambda froz_val: type(froz_val.value) is cls
         return self.get_by_predicate(predicate, **kwargs)
 
-    def get_by_id(self, id_, qual=False, full_qual=False, **kwargs):
+    def get_by_id(self, id_pattern, qual=False, full_qual=False, **kwargs):
+        """
+        Get all :class:`FrozenExprVal` contained in this database which ID
+        matches the given pattern.
+
+        :param id_pattern: :func:`fnmatch.fnmatch` pattern used to match the ID.
+        :type id_pattern: str
+
+        :param qual: If True, the match will be performed on the qualified ID.
+        :type qual: bool
+
+        :param full_qual: If True, the match will be performed on the fully
+            qualified ID.
+        :type full_qual: bool
+
+        :param kwargs: Keyword arguments forwarded to
+            :meth:`ValueDB.get_by_predicate`
+        :type kwargs: dict
+        """
         def predicate(froz_val):
             return utils.match_name(
                 froz_val.get_id(qual=qual, full_qual=full_qual),
-                [id_]
+                [id_pattern]
             )
 
         return self.get_by_predicate(predicate, **kwargs)
 
 
 class ScriptValueDB:
+    """
+    Class tying together a generated script and a :class:`ValueDB`.
+
+    :param db: :class:`ValueDB` used.
+    :type db: ValueDB
+
+    :param var_name: Name of the variable used to represent the
+        :class:`ValueDB` in the generated script.
+    :type var_name: str
+    """
     def __init__(self, db, var_name='db'):
         self.db = db
         self.var_name = var_name
@@ -368,10 +509,20 @@ class ScriptValueDB:
         )
 
 class CycleError(Exception):
+    """
+    Exception raised when a cyclic dependency is detected when building the
+    :class:`Expression` out of a set of callables.
+    """
     pass
 
 
 class ExprHelpers(collections.abc.Mapping):
+    """
+    Helper class used by all expression-like classes.
+
+    It mainly implements the mapping protocol, with keys being parameters and
+    values being subexpressions computing the value of these parameters.
+    """
     def __getitem__(self, k):
         return self.param_map[k]
 
@@ -391,6 +542,18 @@ class ExprHelpers(collections.abc.Mapping):
 
 
 class ExpressionBase(ExprHelpers):
+    """
+    Base class of all expressions proper.
+
+    :param op: Operator to call for that expression
+    :type op: Operator
+
+    :param param_map: Mapping of parameter names to other
+        :class:`ExpressionBase`. The mapping must maintain its order, so that
+        it is possible to get the parameter list in the order it was defined in
+        the sources.
+    :type param_map: collections.OrderedDict
+    """
     def __init__(self, op, param_map):
         self.op = op
         # Map of parameters to other Expression
@@ -399,8 +562,8 @@ class ExpressionBase(ExprHelpers):
     @classmethod
     def cse(cls, expr_list):
         """
-        Apply a flavor of common subexpressions elimination to the
-        Expression.
+        Apply a flavor of common subexpressions elimination to the list of
+        :class:`ExpressionBase`.
         """
 
         expr_map = {}
@@ -443,6 +606,17 @@ class ExpressionBase(ExprHelpers):
         return shared_op_set
 
     def clone_by_predicate(self, predicate):
+        """
+        Create a new :class:`ExpressionBase`, with the outer levels cloned and
+        the inner sub expressions shared with the original one.
+
+        :param predicate: Predicate called on :class:`ExpressionBase` used to
+            know at what level the sub expressions should not be cloned
+            anymore, but instead shared with the original
+            :class:`ExpressionBase`. All parents of a shared expression will be
+            shared no matter what to ensure consistent expressions.
+        :type predicate: collections.abc.Callable
+        """
         shared_op_set = self._find_shared_op_set(predicate, False)
         return self._clone(shared_op_set)
 
@@ -468,14 +642,25 @@ class ExpressionBase(ExprHelpers):
             id = hex(id(self))
         )
 
-    def get_structure(self, full_qual=True, graphviz=False):
+    def format_structure(self, full_qual=True, graphviz=False):
+        """
+        Format the expression in a human readable way.
+
+        :param full_qual: If True, use fully qualified IDs.
+        :type full_qual: bool
+
+        :param graphviz: If True, return a graphviz description suitable for
+            the ``dot`` graph rendering tool.
+        :param graphviz: bool
+        """
+
         if graphviz:
-            return self._get_graphviz_structure(full_qual, level=0, visited=set())
+            return self._format_graphviz_structure(full_qual, level=0, visited=set())
         else:
-            return self._get_structure(full_qual=full_qual)
+            return self._format_structure(full_qual=full_qual)
 
     @staticmethod
-    def _get_structure_op_name(op):
+    def _format_structure_op_name(op):
         if isinstance(op, ConsumerOperator):
             return op.get_name(full_qual=True)
         elif isinstance(op, PrebuiltOperator):
@@ -483,17 +668,17 @@ class ExpressionBase(ExprHelpers):
         else:
             return op.get_name(full_qual=True)
 
-    def _get_structure(self, full_qual=True, indent=1):
+    def _format_structure(self, full_qual=True, indent=1):
         indent_str = 4 * ' ' * indent
 
-        op_name = self._get_structure_op_name(self.op)
+        op_name = self._format_structure_op_name(self.op)
         out = '{op_name} ({value_type_name})'.format(
             op_name = op_name,
             value_type_name = utils.get_name(self.op.value_type, full_qual=full_qual),
         )
         if self.param_map:
             out += ':\n'+ indent_str + ('\n'+indent_str).join(
-                '{param}: {desc}'.format(param=param, desc=desc._get_structure(
+                '{param}: {desc}'.format(param=param, desc=desc._format_structure(
                     full_qual=full_qual,
                     indent=indent+1
                 ))
@@ -501,13 +686,13 @@ class ExpressionBase(ExprHelpers):
             )
         return out
 
-    def _get_graphviz_structure(self, full_qual, level, visited):
+    def _format_graphviz_structure(self, full_qual, level, visited):
         if self in visited:
             return ''
         else:
             visited.add(self)
 
-        op_name = self._get_structure_op_name(self.op)
+        op_name = self._format_structure_op_name(self.op)
 
         # Use the Python id as it is guaranteed to be unique during the lifetime of
         # the object, so it is a good candidate to refer to a node
@@ -537,7 +722,7 @@ class ExpressionBase(ExprHelpers):
                 )
 
                 out.append(
-                    param_expr._get_graphviz_structure(
+                    param_expr._format_graphviz_structure(
                         full_qual=full_qual,
                         level=level+1,
                         visited=visited,
@@ -553,6 +738,33 @@ class ExpressionBase(ExprHelpers):
         return node_out.format(';\n'.join(line for line in out if line.strip()))
 
     def get_id(self, *args, marked_expr_val_set=set(), **kwargs):
+        """
+        Return the ID of the expression.
+
+        :param marked_expr_val_set: If True, return a two-line strings with the
+            second line containing marker characters under the ID of all
+            :class:`ExpressionBase` specified in that set.
+        :type marked_expr_val_set: set(ExpressionBase)
+
+        :param with_tags: Add the tags extracted from the values of each
+            :class:`ExprVal`.
+        :type with_tags: bool
+
+        :param qual: If True, return the qualified ID.
+        :type qual: bool
+
+        :param full_qual: If True, return the fully qualified ID.
+        :type full_qual: bool
+
+        :param style: If ``"rst"``, return a Sphinx reStructuredText string
+            with references to types.
+        :type style: str or None
+
+        :param hidden_callable_set: Hide the ID of all callables given in that
+            set, including their parent's ID.
+        :type hidden_callable_set: set(collections.abc.Callable)
+        """
+
         id_, marker = self._get_id(*args,
             marked_expr_val_set=marked_expr_val_set,
             **kwargs
@@ -695,10 +907,49 @@ class ExpressionBase(ExprHelpers):
             return (id_, marker_str)
 
     def get_script(self, *args, **kwargs):
+        """
+        Return a script equivalent to that :class:`ExpressionBase`.
+
+        :param kwargs: Keyword arguments forwarded to :meth:`get_all_script`.
+        :type kwargs: dict
+        """
         return self.get_all_script([self], *args, **kwargs)
 
     @classmethod
     def get_all_script(cls, expr_list, prefix='value', db_path='VALUE_DB.pickle.xz', db_relative_to=None, db=None, adaptor_cls=None):
+        """
+        Return a script equivalent to executing the specified
+        :class:`ExpressionBase`.
+
+        :param expr_list: List of :class:`ExpressionBase` to turn into a script
+        :type expr_list: list(ExpressionBase)
+
+        :param prefix: Prefix used to name variables containing the values of
+            expressions of ``expr_list``.
+        :type prefix: str
+
+        :param db_path: Path to the serialized :class:`ValueDB` that contains
+            the :class:`FrozenExprVal` of the expressions in ``expr_list``.
+            This is used to generate commented-out code allowing to deserialize
+            values instead of calling the operator again.
+        :type db_path: str
+
+        :param relative_to: Passed to :meth:`ValueDB.from_path` when the
+            :class:`ValueDB` is opened at the beginning of the script. This can
+            typically be set to ``__file__``, so that the script will be able
+            to refer to the :class:`ValueDB` using a relative path.
+        :type relative_to: str
+
+        :param db: :class:`ValueDB` containing the :class:`FrozenExprVal` that
+            were computed when computing expressions of ``expr_list``. If None
+            is provided, a new :class:`ValueDB` object will be built assuming
+            ``expr_list`` is a list of :class:`ComputableExpression`.
+        :type db: ValueDB or None
+
+        :param adaptor_cls: If ``db=None``, used to build a new
+            :class:`ValueDB`.
+        :type adaptor_cls: type
+        """
         assert expr_list
 
         if db is None:
@@ -728,7 +979,7 @@ class ExpressionBase(ExprHelpers):
                 '#'*80 + '\n# Computed expressions:' +
                 make_comment(expr.get_id(mark_excep=True, full_qual=False))
                 + '\n' +
-                make_comment(expr.get_structure()) + '\n\n'
+                make_comment(expr.format_structure()) + '\n\n'
             )
             idt = IndentationManager(' '*4)
 
@@ -1150,6 +1401,19 @@ class ExpressionBase(ExprHelpers):
 
 
 class ComputableExpression(ExpressionBase):
+    """
+    Expression that also contains its computed values.
+
+    :param data: :class:`ExprData` to use when computing the values of the
+        expression. The ``data`` of the root :class:`ComputableExpression` will
+        be used for all the subexpressions as well during the execution.
+    :type data: ExprData or None
+
+    .. seealso:: :class:`ExpressionBase`
+
+    Instances of this class contains values, whereas :class:`Expression` do
+    not.
+    """
     def __init__(self, op, param_map, data=None):
         self.uuid = utils.create_uuid()
         self.expr_val_seq_list = list()
@@ -1158,6 +1422,12 @@ class ComputableExpression(ExpressionBase):
 
     @classmethod
     def from_expr(cls, expr, **kwargs):
+        """
+        Build an instance from an :class:`ExpressionBase`
+
+        :param kwargs: Keyword arguments forwarded to ``__init__``
+        :type kwargs: dict
+        """
         param_map = OrderedDict(
             (param, cls.from_expr(param_expr))
             for param, param_expr in expr.param_map.items()
@@ -1170,6 +1440,12 @@ class ComputableExpression(ExpressionBase):
 
     @classmethod
     def from_expr_list(cls, expr_list):
+        """
+        Build an a list of instances from a list of :class:`ExpressionBase`.
+
+        .. note:: Common Subexpression Elimination using
+            :meth:`ExpressionBase.cse` will be applied on the resulting list.
+        """
         # Apply Common Subexpression Elimination to ExpressionBase before they
         # are run
         return cls.cse(
@@ -1183,6 +1459,18 @@ class ComputableExpression(ExpressionBase):
         )
 
     def get_id(self, mark_excep=False, marked_expr_val_set=set(), **kwargs):
+        """
+        Return the ID of the expression.
+
+        :param mark_excep: Mark expressions listed by :meth:`get_excep`.
+        :type mark_excep: bool
+
+        :param marked_expr_val_set: If ``mark_excep=False`` mark these
+            exceptions, otherwise it is ignored.
+        :type marked_expr_val_set: bool
+
+        .. seealso:: :meth:`ExpressionBase.get_id`
+        """
         # Mark all the values that failed to be computed because of an
         # exception
         marked_expr_val_set = self.get_excep() if mark_excep else marked_expr_val_set
@@ -1193,6 +1481,15 @@ class ComputableExpression(ExpressionBase):
         )
 
     def find_expr_val_seq_list(self, param_map):
+        """
+        Return a list of :class:`ExprValSeq` that were computed using the given
+        parameters.
+
+        :param param_map: Mapping of parameter names to values
+        :type param_map: collections.OrderedDict
+
+        .. note:: ``param_map`` will be checked as a subset of the parameters.
+        """
         def value_map(param_map):
             return ExprValParamMap(
                 # Extract the actual value from ExprVal
@@ -1213,6 +1510,21 @@ class ComputableExpression(ExpressionBase):
 
     @classmethod
     def execute_all(cls, expr_list, *args, **kwargs):
+        """
+        Execute all expressions of ``expr_list`` after applying Common
+        Expression Elimination and yield tuples of (:class:`ExpressionBase`,
+        :class:`ExprVal`).
+
+        :param expr_list: List of expressions to execute
+        :type expr_list: list(ExpressionBase)
+
+        :param kwargs: Keyword arguments forwarded to
+            :meth:`execute`.
+        :type kwargs: dict
+
+        .. seealso: :meth:`execute` and
+            :meth:`from_expr_list`.
+        """
         for comp_expr in cls.from_expr_list(expr_list):
             for expr_val in comp_expr.execute(*args, **kwargs):
                 yield (comp_expr, expr_val)
@@ -1265,6 +1577,16 @@ class ComputableExpression(ExpressionBase):
         return expr
 
     def prepare_execute(self):
+        """
+        Prepare the expression for execution.
+
+        This includes appropriate cloning of expressions using
+        :class:`ConsumerOperator` and :class:`ExprData`.
+
+        .. note:: Calling this method manually is only useful to get more
+            accurate graphs when showing the structure of the expression, since
+            it is done in any case by :meth:`execute`.`
+        """
         # Make sure the Expressions referencing their Consumer get
         # appropriately cloned.
         self._clone_consumer([])
@@ -1272,6 +1594,17 @@ class ComputableExpression(ExpressionBase):
         return self
 
     def execute(self, post_compute_cb=None):
+        """
+        Execute the expression and yield its :class:`ExprVal`.
+
+        :param post_compute_cb: Callback called after every computed value. It
+            takes two parameters: 1) the :class:`ExprVal` that was just
+            computed and 2) a boolean that is ``True`` if the :class:`ExprVal`
+            was merely reused and ``False`` if it was actually computed.
+        :type post_compute_cb: collections.abc.Callable
+
+        .. note:: The :meth:`prepare_execute` is called prior to executing.
+        """
         # Call it in case it was not already done.
         self.prepare_execute()
         return self._execute(post_compute_cb)
@@ -1352,18 +1685,39 @@ class ComputableExpression(ExpressionBase):
             yield from expr_val_seq.iter_expr_val()
 
     def get_all_vals(self):
+        """
+        Get all :class:`ExprVal` that were computed for that expression.
+        """
         return utils.flatten_seq(
             expr_val_seq.expr_val_list
             for expr_val_seq in self.expr_val_seq_list
         )
 
     def get_excep(self):
+        """
+        Get all :class:`ExprVal` containing an exception that are reachable
+        from :class:`ExprVal` computed for that expression.
+        """
         return set(utils.flatten_seq(
             expr_val.get_excep()
             for expr_val in self.get_all_vals()
         ))
 
 class ClassContext:
+    """
+    Collect callables and types that put together will be used to create
+    :class:`Expression`.
+
+    :param op_map: Mapping of types to list of :class:`Operator` that can
+        produce that type.
+    :type op_map: dict(type, list(Operator))
+
+    :param cls_map: Mapping of types to a list of compatible types. A common
+        "compatibility" relation is ``issubclass``. In that case, keys are
+        classes and values are the list of all (direct and indirect)
+        subclasses.
+    :type cls_map: dict(type, list(type))
+    """
     def __init__(self, op_map, cls_map):
         self.op_map = op_map
         self.cls_map = cls_map
@@ -1449,6 +1803,27 @@ class ClassContext:
 
     @classmethod
     def from_op_set(cls, op_set, forbidden_pattern_set=set(), restricted_pattern_set=set(), compat_cls=issubclass):
+        """
+        Build an :class:`ClassContext` out of a set of :class:`Operator`.
+
+        :param op_set: Set of :class:`Operator` to consider.
+        :type op_set: set(Operator)
+
+        :param forbidden_pattern_set: Set :func:`fnmatch.fnmatch` type name
+            patterns that are not allowed to be produced.
+        :type forbidden_pattern_set: set(str)
+
+        :parm restricted_pattern_set: Set of :func:`fnmatch.fnmatch`
+            :class:`Operator` ID pattern. Operators matching that pattern will
+            be the only one allowed to produce the type they are producing, or
+            any other compatible type.
+        :type restricted_pattern_set: set(str)
+
+        :param compat_cls: Callable defining the compatibility relation between
+            two classes. It will be called on two classes and shall return
+            ``True`` if the classes are compatible, ``False`` otherwise.
+        :type compat_cls: collections.abc.Callable
+        """
         # Build the mapping of compatible classes
         cls_map = cls._build_cls_map(op_set, compat_cls)
         # Build the mapping of classes to producing operators
@@ -1460,8 +1835,47 @@ class ClassContext:
             cls_map=cls_map
         )
 
-    def build_expr_list(self, result_op_seq,
+    def build_expr_list(self, result_op_set,
             non_produced_handler='raise', cycle_handler='raise'):
+        """
+        Build a list of consistent :class:`Expression`.
+
+        :param result_op_set: Set of :class:`Operator` that will constitute the
+            roots of expressions.
+        :type result_op_set: set(Operator)
+
+        :param non_produced_handler: Handler to be used when a needed type is
+            produced by no :class:`Operator`:
+
+                * ``raise``: will raise a :class:`NoOperatorError` exception
+                * ``ignore``: the expression will be ignored
+                * a callback: called with the following parameters:
+
+                    * __qualname__ of the type that cannot be produced.
+                    * name of the :class:`Operator` for which a value of the
+                      type was needed.
+                    * name of the parameter for which a value of the type was
+                      needed.
+                    * a stack (tuple) of callables which is the path leading
+                      from the root expression to the operator for which the
+                      type was needed.
+
+        :type non_produced_handler: str or collections.abc.Callable
+
+        :param cycle_handler: Handler to be used when a cycle is detected in
+            the built :class:`Expression`:
+
+                * ``raise``: will raise a :class:`CycleError` exception
+                * ``ignore``: the expression will be ignored
+                * a callback: called with a tuple of callables constituting the
+                  cycle.
+
+        :type cycle_handler: str or collections.abc.Callable
+
+        All combinations of compatible classes and operators will be generated.
+        """
+
+
         op_map = copy.copy(self.op_map)
         cls_map = {
             cls: compat_cls_set
@@ -1480,7 +1894,7 @@ class ClassContext:
         cls_map[Consumer] = [Consumer]
 
         expr_list = list()
-        for result_op in result_op_seq:
+        for result_op in result_op_set:
             expr_gen = self._build_expr(result_op, op_map, cls_map,
                 op_stack = [],
                 non_produced_handler=non_produced_handler,
@@ -1615,13 +2029,29 @@ class ClassContext:
                         yield Expression(op, param_map)
 
 class Expression(ExpressionBase):
+    """
+    Static subclass :class:`ExpressionBase` tying :class:`Operator` with its
+    parameters.
+
+    Instances of this class do not contain any computed values, they can be
+    considered as read-only structure.
+
+    .. seealso:: :class:`ComputableExpression`.
+    """
     def validate(self, op_map):
-        type_map, valid = self._get_type_map()
+        """
+        Check that the Expression does not involve two classes that are
+        compatible.
+
+        This ensures that only one class of each "category" will be used in
+        each expression, so that all references to that class will point to the
+        same expression after :meth:`ExpressionBase.cse` is applied.
+        """
+        type_map = dict()
+        valid = self._populate_type_map(type_map)
         if not valid:
             return False
 
-        # Check that the Expression does not involve 2 classes that are
-        # compatible
         cls_bags = [set(cls_list) for cls_list in op_map.values()]
         cls_used = set(type_map.keys())
         for cls1, cls2 in itertools.product(cls_used, repeat=2):
@@ -1631,10 +2061,6 @@ class Expression(ExpressionBase):
 
         return True
 
-    def _get_type_map(self):
-        type_map = dict()
-        return (type_map, self._populate_type_map(type_map))
-
     def _populate_type_map(self, type_map):
         value_type = self.op.value_type
         # If there was already an Expression producing that type, the Expression
@@ -1650,17 +2076,41 @@ class Expression(ExpressionBase):
         return True
 
 class AnnotationError(Exception):
+    """
+    Exception raised when there is a missing PEP 484 annotation.
+    """
     pass
 
 class PartialAnnotationError(AnnotationError):
+    """
+    Exception raised when there is a missing PEP 484 annotation, but other
+    parameters are annotated.
+
+    This usually indicates a missing annotation in a function otherwise
+    supposed to be annotated.
+    """
     pass
 
 class ForcedParamType:
+    """
+    Base class for types placeholders used when forcing the value of a
+    parameter using :meth:`Operator.force_param`.
+    """
     pass
 
 class UnboundMethod:
     """
-    Wrap a function in a similar way to Python 2 unbound methods
+    Wrap a function in a similar way to Python 2 unbound methods.
+
+    :param callable_: method to wrap.
+    :type callable_: collections.abc.Callable
+
+    :param cls: Class on which the method is available.
+    :type cls: type
+
+    .. note:: It is generally assumed that if a given method is wrapped in an
+        :class:`UnboundMethod`, all subclasses will also have that method
+        wrapped the same way.
     """
     def __init__(self, callable_, cls):
         self.cls = cls
@@ -1688,6 +2138,22 @@ class UnboundMethod:
         return hash(self.__wrapped__) ^ hash(self.cls)
 
 class Operator:
+    """
+    Wrap a callable.
+
+    :param callable_: callable to represent.
+    :type callable_: collections.abc.Callable
+
+    :param non_reusable_type_set: Set of non reusable types. If the callable
+        produces a subclass of these types, it will be considered as
+        non-reusable.
+    :type non_reusable_type_set: set(type)
+
+    :param tags_getter: Callback used to get the tags for the objects returned
+        by the callable. It takes the object as argument, and is expected to
+        return a mapping of tags names to values.
+    :type tags_getter: collections.abc.Callable
+    """
     def __init__(self, callable_, non_reusable_type_set=None, tags_getter=None):
         if non_reusable_type_set is None:
             non_reusable_type_set = set()
@@ -1738,6 +2204,9 @@ class Operator:
 
     @property
     def callable_globals(self):
+        """
+        Returns a dictionnary of global variables as seen by the callable.
+        """
         globals_ = self.resolved_callable.__globals__
         # Make sure the class name can be resolved
         if isinstance(self.callable_, UnboundMethod):
@@ -1747,14 +2216,28 @@ class Operator:
 
     @property
     def signature(self):
+        """
+        :class:`inspect.Signature` of the callable.
+        """
         return inspect.signature(self.resolved_callable)
 
     def __repr__(self):
         return '<Operator of ' + str(self.callable_) + '>'
 
-    def force_param(self, param_callable_map, tags_getter=None):
+    def force_param(self, param_value_map, tags_getter=None):
+        """
+        Force the value of a given parameter of the callable.
+
+        :param param_value_map: Mapping of parameter names to list of values
+            that this parameter should take.
+        :type param_value_map: dict(str, list(object))
+
+        :param tags_getter: Callable used to return the tags for the values of
+            the parameter. Same as :class:`Operator`'s ``__init__`` parameter.
+        :type tags_getter: collections.abc.Callable
+        """
         prebuilt_op_set = set()
-        for param, value_list in param_callable_map.items():
+        for param, value_list in param_value_map.items():
             # Get the most derived class that is in common between all
             # instances
             value_type = utils.get_common_base(type(v) for v in value_list)
@@ -1798,6 +2281,10 @@ class Operator:
 
     @property
     def resolved_callable(self):
+        """
+        Fully unwrapped callable. If the callable is a class, it's ``__init__``
+        will be returned.
+        """
         unwrapped = self.unwrapped_callable
         # We use __init__ when confronted to a class
         if inspect.isclass(unwrapped):
@@ -1806,15 +2293,35 @@ class Operator:
 
     @property
     def unwrapped_callable(self):
+        """
+        Fully unwrapped callable.
+
+        .. seealso:: :func:`functools.wraps`
+        """
         return inspect.unwrap(self.callable_)
 
     def get_name(self, *args, **kwargs):
+        """
+        Get the name of the callable, or None if no name can be retrieved.
+        """
         try:
             return utils.get_name(self.callable_, *args, **kwargs)
         except AttributeError:
             return None
 
     def get_id(self, full_qual=True, qual=True, style=None):
+        """
+        Get the ID of the operator.
+
+        :param full_qual: Fully qualified name, including the module name.
+        :type full_qual: bool
+
+        :param qual: Qualified name.
+        :type qual: bool
+
+        :param style: If ``rst``, a Sphinx reStructuredText string is returned.
+        :type style: str or None
+        """
         if style == 'rst':
             if self.is_factory_cls_method:
                 qualname = utils.get_name(self.value_type, full_qual=True)
@@ -1841,14 +2348,21 @@ class Operator:
 
     @property
     def name(self):
+        """
+        Same as :meth:`get_name`
+        """
         return self.get_name()
 
-    @property
-    def id_(self):
-        return self.get_id()
-
     @property
     def mod_name(self):
+        """
+        Name of the module the callable is defined in.
+
+        If the callable is an :class:`UnboundMethod`, the module of its class
+        is returned.
+
+        .. note:: The callable is first unwrapped.
+        """
         try:
             if isinstance(self.callable_, UnboundMethod):
                 module = inspect.getmodule(self.callable_.cls)
@@ -1862,22 +2376,39 @@ class Operator:
 
     @property
     def src_loc(self):
+        """
+        Get the source location of the unwrapped callable.
+
+        .. seealso:: :func:`exekall._utils.get_src_loc`
+        """
         return utils.get_src_loc(self.unwrapped_callable)
 
     @property
     def value_type(self):
+        """
+        Annotated return type of the callable.
+        """
         return self.get_prototype()[1]
 
     @property
     def is_genfunc(self):
+        """
+        ``True`` if the callable is a generator function.
+        """
         return inspect.isgeneratorfunction(self.resolved_callable)
 
     @property
     def is_class(self):
+        """
+        ``True`` if the callable is a class.
+        """
         return inspect.isclass(self.unwrapped_callable)
 
     @property
     def is_static_method(self):
+        """
+        ``True`` if the callable is a ``staticmethod``.
+        """
         callable_ = self.unwrapped_callable
 
         try:
@@ -1907,6 +2438,9 @@ class Operator:
 
     @property
     def is_method(self):
+        """
+        ``True`` if the callable is a plain method.
+        """
         if self.is_cls_method or self.is_static_method:
             return False
         elif isinstance(self.callable_, UnboundMethod):
@@ -1925,6 +2459,9 @@ class Operator:
 
     @property
     def is_cls_method(self):
+        """
+        ``True`` if the callable is a ``classmethod``.
+        """
         # Class methods appear as a bound method object when referenced through
         # their class. The method is bound to a class, which is not the case
         # if this is not a class method.
@@ -1935,10 +2472,18 @@ class Operator:
 
     @property
     def is_factory_cls_method(self):
+        """
+        ``True`` if the callable is a factory ``classmethod``, i.e. a
+        classmethod that returns objects of the class it is defined in (or of a
+        subclass of it).
+        """
         return self.is_cls_method and issubclass(self.unwrapped_callable.__self__, self.value_type)
 
     @property
     def generator_wrapper(self):
+        """
+        Wrap the callable in a generator suitable for execution.
+        """
         if self.is_genfunc:
             @functools.wraps(self.callable_)
             def genf(*args, **kwargs):
@@ -1969,6 +2514,12 @@ class Operator:
         return genf
 
     def get_prototype(self):
+        """
+        Return the prototype of the callable as a tuple of:
+
+            * map of parameter names to types
+            * return type
+        """
         sig = self.signature
         first_param = utils.take_first(sig.parameters)
         annotations = self.annotations
@@ -2053,6 +2604,22 @@ class Operator:
         return (param_map, produced)
 
 class PrebuiltOperator(Operator):
+    """
+    :class:`Operator` that injects prebuilt objects.
+
+    :param obj_type: Type of the objects that are injected.
+    :type obj_type: type
+
+    :param obj_list: List of objects to inject
+    :type obj_list: list(object)
+
+    :param id_: ID of the operator.
+    :type id_: str or None
+
+    :param kwargs: Keyword arguments forwarded to :class:`Operator`
+        constructor.
+    :type kwargs: dict
+    """
     def __init__(self, obj_type, obj_list, id_=None, **kwargs):
         obj_list_ = list()
         uuid_list = list()
@@ -2105,6 +2672,14 @@ class PrebuiltOperator(Operator):
         return genf
 
 class ConsumerOperator(PrebuiltOperator):
+    """
+    Placeholder operator used to represent the consumer of the an expression
+    asking for it.
+
+    :param consumer: Callable that will consume the value of the expression
+        refering to its consumer.
+    :type consumer: collections.abc.Callable
+    """
     def __init__(self, consumer=None):
         obj_type = Consumer
         super().__init__(
@@ -2126,6 +2701,12 @@ class ConsumerOperator(PrebuiltOperator):
         return self.obj_list[0]
 
 class ExprDataOperator(PrebuiltOperator):
+    """
+    Placeholder operator for :class:`ExprData`.
+
+    The :class:`ExprData` that will be used is the same throughout an
+    expression, and is the one of the root expression.
+    """
     def __init__(self, data=None):
         obj_type = ExprData
         super().__init__(
@@ -2147,6 +2728,27 @@ class ExprDataOperator(PrebuiltOperator):
         pass
 
 class ExprValSeq:
+    """
+    Sequence of :class:`ExprVal` produced by an :class:`ComputableExpression`.
+
+    :param expr: :class:`ComputableExpression` that was used to compute the
+        values.
+    :type expr: ComputableExpression
+
+    :param iterator: Iterator that yields the values. This is used when the
+        expressions are being executed.
+    :type iterator: collections.abc.Iterator
+
+    :param param_map: Ordered mapping of parameters name to :class:`ExprVal`
+        used to compute the recored :class:`ExprVal`.
+    :type param_map: collections.OrderedDict
+
+    :param post_compute_cb: See :meth:`ComputableExpression.execute`
+    :type post_compute_cb: collections.abc.Callable
+
+    Since :class:`ComputableExpression` can represent generator functions, they
+    are allowed to create multiple :class:`ExprVal`.
+    """
     def __init__(self, expr, iterator, param_map, post_compute_cb=None):
         self.expr = expr
         assert isinstance(iterator, collections.abc.Iterator)
@@ -2157,6 +2759,11 @@ class ExprValSeq:
 
     @classmethod
     def from_one_expr_val(cls, expr, expr_val, param_map):
+        """
+        Build an :class:`ExprValSeq` out of a single :class:`ExprVal`.
+
+        .. seealso:: :class:`ExprValSeq` for parameters description.
+        """
         iterated = [
             (expr_val.uuid, expr_val.value, expr_val.excep)
         ]
@@ -2174,6 +2781,11 @@ class ExprValSeq:
         return new
 
     def iter_expr_val(self):
+        """
+        Iterate over the iterator and yield :class:`ExprVal`.
+
+        ``post_compute_cb`` will be called when a value is computed or reused.
+        """
         callback = self.post_compute_cb
         if not callback:
             callback = lambda x, reused: None
@@ -2217,7 +2829,19 @@ class ExprValSeq:
 
 
 class ExprValParamMap(OrderedDict):
+    """
+    Mapping of parameters to :class:`ExprVal` used when computing the value of
+    a :class:`ComputableExpression`.
+    """
     def is_partial(self, ignore_error=False):
+        """
+        Return ``True`` if the map is partial, i.e. some parameters don't have
+        a value.
+
+        That could be because one of them could not be computed due to an
+        exception, or because it was skipped since it could not lead to a
+        result anyway.
+        """
         def is_partial(expr_val):
             # Some arguments are missing: there was no attempt to compute
             # them because another argument failed to be computed
@@ -2237,6 +2861,20 @@ class ExprValParamMap(OrderedDict):
 
     @classmethod
     def from_gen_map(cls, param_gen_map):
+        """
+        Build a :class:`ExprValParamMap` out of a mapping of parameters names
+        and expressions to generators.
+
+        :param param_gen_map: Mapping of tuple(param_name, param_expr) to an
+            iterator that is ready to generate the possible values for the
+            generator.
+        :type param_gen_map: collections.OrderedDict
+
+        Generators are assumed to only yield once.
+
+        .. seealso:: :meth:`from_gen_map_product` for cases where the generator
+            is expected to yield more than once.
+        """
         # Pre-fill UnEvaluatedExprVal with in case we exit the loop early
         param_map = cls(
             (param, UnEvaluatedExprVal(param_expr))
@@ -2257,8 +2895,8 @@ class ExprValParamMap(OrderedDict):
     @classmethod
     def from_gen_map_product(cls, param_gen_map):
         """
-        Yield :class:`collections.OrderedDict` for each combination of parameter
-        values.
+        Yield :class:`collections.OrderedDict` for each combination of
+        parameter values.
 
         :param param_gen_map: Mapping of tuple(param_name, param_expr) to an
             iterator that is ready to generate the possible values for the
@@ -2338,12 +2976,33 @@ class ExprValParamMap(OrderedDict):
         return functools.reduce(reducer, reversed(gen_list), initializer())
 
 class ExprValBase(ExprHelpers):
+    """
+    Base class for classes representing the value of an expression.
+
+    :param param_map: Map of parameter names of the :class:`Operator` that gave
+        this value to their :class:`ExprValBase` value.
+    :type param_map: dict(str, ExprValBase)
+
+    :param value: Value that was computed. If no value was computed,
+        :attr:`exekall._utils.NoValue` will be used.
+    :type value: object
+
+    :param excep: Exception that was raised while computing the value. If no
+        excpetion was raised, :attr:`exekall._utils.NoValue` will be used.
+    :type value: Exception
+    """
     def __init__(self, param_map, value, excep):
         self.param_map = param_map
         self.value = value
         self.excep = excep
 
     def get_by_predicate(self, predicate):
+        """
+        Get a list of parents :class:`ExprValBase` for which the predicate
+        returns ``True``.
+
+        :type predicate: collections.abc.Callable
+        """
         return list(self._get_by_predicate(predicate))
 
     def _get_by_predicate(self, predicate):
@@ -2355,7 +3014,8 @@ class ExprValBase(ExprHelpers):
 
     def get_excep(self):
         """
-        Get all the failed parents.
+        Get all the parents :class:`ExprValBase` for which an exception was
+        raised.
         """
         def predicate(val):
             return val.excep is not NoValue
@@ -2363,6 +3023,17 @@ class ExprValBase(ExprHelpers):
         return self.get_by_predicate(predicate)
 
     def get_by_type(self, cls, include_subclasses=True, **kwargs):
+        """
+        Get a list of parents :class:`ExprValBase` having a value of the given
+        type.
+
+        :param cls: Type to look for.
+        :type cls: type
+
+        :param include_subclasses: If True, the check is done using
+            ``isinstance``, otherwise an exact type check is done using ``is``.
+        :type include_subclasses: bool
+        """
         if include_subclasses:
             predicate = lambda expr_val: isinstance(expr_val.value, cls)
         else:
@@ -2371,6 +3042,58 @@ class ExprValBase(ExprHelpers):
 
 
 class FrozenExprVal(ExprValBase):
+    """
+    Serializable version of :class:`ExprVal`.
+
+    :param uuid: UUID of the :class:`ExprVal`
+    :type uuid: str
+
+    :param callable_qualname: Qualified name of the callable that was used to
+        compute the value, including module name.
+    :type callable_qualname: str
+
+    :param callable_name: Name of the callable that was used to compute the
+        value.
+    :type callable_name: str
+
+    :param recorded_id_map: Mapping of :meth:`ExprVal.get_id` parameters to the
+        corresponding ID. The parameters
+    :type recorded_id_map: dict
+
+    The most important instance attributes are:
+
+    ..  list-table::
+        :widths: auto
+
+        * - ``value``
+          - Value that was computed, or :attr:`~exekall._utils.NoValue` if it
+            was not computed. This could be because of an exception when
+            computing it, or because computing the value was skipped.
+
+        * - ``excep``
+          - Exception that was raised when trying to compute the value, or
+            :attr:`~exekall._utils.NoValue`.
+
+        * - ``uuid``
+          - String UUID of that value. This is unique and can be used to
+            correlate with logs, or deduplicate across multiple
+            :class:`ValueDB`.
+
+
+    Since it is a subclass of :class:`ExprValBase`, the :class:`FrozenExprVal`
+    value of the parameters of the callable that was used to compute it can be
+    accessed using the subscript operator ``[]``.
+
+    Instances of this class will not refer to the callable that was used to
+    create the values, and will record the ID of the values instead of
+    recomputing it from the graph of :class:`ExpressionBase`. This allows
+    manipulating :class:`FrozenExprVal` as standalone objects, with minimal
+    references to the code, which improves robustness against API change that
+    would make deserializing them impossible.
+
+    .. seealso:: :class:`ExprValBase`
+
+    """
     def __init__(self,
             param_map, value, excep, uuid,
             callable_qualname, callable_name, recorded_id_map,
@@ -2396,6 +3119,13 @@ class FrozenExprVal(ExprValBase):
 
     @classmethod
     def from_expr_val(cls, expr_val, hidden_callable_set=None):
+        """
+        Build a :class:`FrozenExprVal` from one :class:`ExprVal`.
+
+        :param hidden_callable_set: Set of callables that should not appear in
+            the ID.
+        :type hidden_callable_set: set(collections.abc.Callable)
+        """
         value = expr_val.value if utils.is_serializable(expr_val.value) else NoValue
         excep = expr_val.excep if utils.is_serializable(expr_val.excep) else NoValue
 
@@ -2453,6 +3183,9 @@ class FrozenExprVal(ExprValBase):
         return tuple(sorted(kwargs.items()))
 
     def get_id(self, full_qual=True, qual=True, with_tags=True):
+        """
+        Return recorded IDs generated using :meth:`ExprVal.get_id`.
+        """
         full_qual = full_qual and qual
         key = self._make_id_key(
             full_qual=full_qual,
@@ -2462,6 +3195,10 @@ class FrozenExprVal(ExprValBase):
         return self.recorded_id_map[key]
 
 class PrunedFrozVal(FrozenExprVal):
+    """
+    Placeholder introduced by :meth:`ValueDB.prune_by_predicate` when a
+    :class:`FrozenExprVal` is pruned.
+    """
     def __init__(self, froz_val):
         super().__init__(
             param_map=OrderedDict(),
@@ -2474,6 +3211,19 @@ class PrunedFrozVal(FrozenExprVal):
         )
 
 class FrozenExprValSeq(collections.abc.Sequence):
+    """
+    Sequence of :class:`FrozenExprVal` analogous to :class:`ExprValSeq`.
+
+    :param froz_val_list: List of :class:`FrozenExprVal`.
+    :type froz_val_list: list(FrozenExprVal)
+
+    :param param_map: Parameter map that was used to compute the :class:`ExprVal`.
+        See :class:`ExprValSeq`.
+    :type param_map: dict
+
+    Since it inherits from :class:`collections.abc.Sequence`, it can be
+    iterated over directly.
+    """
     def __init__(self, froz_val_list, param_map):
         self.froz_val_list = froz_val_list
         self.param_map = param_map
@@ -2486,6 +3236,13 @@ class FrozenExprValSeq(collections.abc.Sequence):
 
     @classmethod
     def from_expr_val_seq(cls, expr_val_seq, **kwargs):
+        """
+        Build a :class:`FrozenExprValSeq` from an :class:`ExprValSeq`.
+
+        :param kwargs: Keyword arguments forwarded to
+            :meth:`FrozenExprVal.from_expr_val`.
+        :type kwargs: dict
+        """
         return cls(
             froz_val_list=[
                 FrozenExprVal.from_expr_val(expr_val, **kwargs)
@@ -2499,6 +3256,19 @@ class FrozenExprValSeq(collections.abc.Sequence):
 
     @classmethod
     def from_expr_list(cls, expr_list, **kwargs):
+        """
+        Build a list of :class:`FrozenExprValSeq` from an list of
+        :class:`ComputableExpression`.
+
+        :param expr_list: List of :class:`ComputableExpression` to extract the
+            :class:`ExprVal` from.
+        :type expr_list: list(ComputableExpression)
+
+        :param kwargs: Keyword arguments forwarded to
+            :meth:`from_expr_val_seq`.
+        :type kwargs: dict
+
+        """
         expr_val_seq_list = utils.flatten_seq(expr.expr_val_seq_list for expr in expr_list)
         return [
             cls.from_expr_val_seq(expr_val_seq, **kwargs)
@@ -2507,6 +3277,17 @@ class FrozenExprValSeq(collections.abc.Sequence):
 
 
 class ExprVal(ExprValBase):
+    """
+    Value computed when executing :class:`ComputableExpression`.
+
+    :param expr: Expression for which this value was computed
+    :type expr: ExpressionBase
+
+    :param uuid: UUID of the value.
+    :type uuid: str
+
+    .. seealso:: :class:`ExprValBase` for the other parameters.
+    """
     def __init__(self, expr, param_map,
         value=NoValue, excep=NoValue, uuid=None,
     ):
@@ -2515,6 +3296,9 @@ class ExprVal(ExprValBase):
         super().__init__(param_map=param_map, value=value, excep=excep)
 
     def format_tags(self):
+        """
+        Return a formatted string for the tags of that :class:`ExprVal`.
+        """
         tag_map = {
             # Make sure there are no brackets in tag values, since that
             # would break all regex parsing done on IDs.
@@ -2531,6 +3315,10 @@ class ExprVal(ExprValBase):
 
     @classmethod
     def validate(cls, expr_val_list):
+        """
+        Check that the list contains only one :class:`ExprVal` for each
+        :class:`ComputableExpression`, unless it is non reusable.
+        """
         expr_map = {}
         def update_map(expr_val1):
             # The check does not apply for non-reusable operators, since it is
@@ -2556,6 +3344,9 @@ class ExprVal(ExprValBase):
             return True
 
     def get_id(self, *args, with_tags=True, **kwargs):
+        """
+        See :class:`ExpressionBase.get_id`.
+        """
         return self.expr.get_id(
             with_tags=with_tags,
             expr_val=self,
@@ -2563,6 +3354,10 @@ class ExprVal(ExprValBase):
         )
 
 class UnEvaluatedExprVal(ExprVal):
+    """
+    Placeholder :class:`ExprVal` created when computing the value was known to
+    not lead to anything useful.
+    """
     def __init__(self, expr):
         super().__init__(
             expr=expr,
@@ -2575,10 +3370,21 @@ class UnEvaluatedExprVal(ExprVal):
         )
 
 class Consumer:
+    """
+    Placeholder type used in PEP 484 annotations by callables to refer to the
+    callable that will use their value.
+
+    .. note:: This leads to cloning the expression refering to its consumer for
+        each different consumer.
+    """
     def __init__(self):
         pass
 
 class ExprData(dict):
+    """
+    Placeholder type used in PEP 484 annotations by callables to refer to the
+    expression-wide data dictionnary.
+    """
     def __init__(self):
         super().__init__()
         self.uuid = utils.create_uuid()
diff --git a/tools/exekall/exekall/main.py b/tools/exekall/exekall/main.py
index c34aa6e7093ff1a2382cea020a4c4208e58288b2..c896606a2769eb7dde25b6c40ca57979532b2062 100755
--- a/tools/exekall/exekall/main.py
+++ b/tools/exekall/exekall/main.py
@@ -33,7 +33,7 @@ import sys
 
 from exekall.customization import AdaptorBase
 import exekall.utils as utils
-from exekall.utils import NoValue, error, warn, debug, info, out
+from exekall.utils import NoValue, error, warn, debug, info, out, add_argument
 import exekall.engine as engine
 
 DB_FILENAME = 'VALUE_DB.pickle.xz'
@@ -197,14 +197,18 @@ PATTERNS
     """,
     formatter_class=argparse.RawTextHelpFormatter)
 
-    parser.add_argument('--debug', action='store_true',
+    add_argument(parser, '--debug', action='store_true',
         help="""Show complete Python backtrace when exekall crashes.""")
 
     subparsers = parser.add_subparsers(title='subcommands', dest='subcommand')
 
     run_parser = subparsers.add_parser('run',
     description="""
-    Run the tests
+Run expressions
+
+Note that the adaptor in the customization module is able to add more
+parameters to ``exekall run``. In order to get the complete set of options,
+please run ``exekall run YOUR_SOURCES --help``.
     """,
     formatter_class=argparse.RawTextHelpFormatter)
 
@@ -212,13 +216,13 @@ PATTERNS
     # otherwise adaptor-specific options' values will be picked up as Python
     # sources, and importing the modules will therefore fail with unknown files
     # error.
-    run_parser.add_argument('python_files', nargs='+',
+    add_argument(run_parser, 'python_files', nargs='+',
         metavar='PYTHON_SRC',
         help="""Python modules files. If passed a folder, all contained files recursively are selected. By default, the current directory is selected.""")
 
 
-    run_parser.add_argument('-s', '--select', action='append',
-        metavar='SELECT_PATTERN',
+    add_argument(run_parser, '-s', '--select', action='append',
+        metavar='ID_PATTERN',
         default=[],
         help="""Only run the expressions with an ID matching any of the supplied filters.""")
 
@@ -226,86 +230,86 @@ PATTERNS
     # repeat the option. This is mostly available to support wrapper
     # scripts, and is not recommended for direct use since it can lead to
     # some parsing ambiguities.
-    run_parser.add_argument('--select-multiple', nargs='*',
+    add_argument(run_parser, '--select-multiple', nargs='*',
         default=[],
         help=argparse.SUPPRESS,
     )
 
-    run_parser.add_argument('--list', action='store_true',
+    add_argument(run_parser, '--list', action='store_true',
         help="""List the expressions that will be run without running them.""")
 
     # Show the list of expressions in reStructuredText format, suitable for
     # inclusion in Sphinx documentation
-    run_parser.add_argument('--rst-list', action='store_true',
+    add_argument(run_parser, '--rst-list', action='store_true',
         help=argparse.SUPPRESS)
 
-    run_parser.add_argument('--log-level', default='info',
+    add_argument(run_parser, '--log-level', default='info',
         choices=('debug', 'info', 'warn', 'error', 'critical'),
         help="""Change the default log level of the standard logging module.""")
 
-    run_parser.add_argument('--verbose', '-v', action='count', default=0,
+    add_argument(run_parser, '--verbose', '-v', action='count', default=0,
         help="""More verbose output. Can be repeated for even more verbosity. This only impacts exekall output, --log-level for more global settings.""")
 
     artifact_dir_group = run_parser.add_mutually_exclusive_group()
-    artifact_dir_group.add_argument('--artifact-root',
+    add_argument(artifact_dir_group, '--artifact-root',
         default=os.getenv('EXEKALL_ARTIFACT_ROOT', 'artifacts'),
         help="Root folder under which the artifact folders will be created. Defaults to EXEKALL_ARTIFACT_ROOT env var.")
 
-    artifact_dir_group.add_argument('--artifact-dir',
+    add_argument(artifact_dir_group, '--artifact-dir',
         default=os.getenv('EXEKALL_ARTIFACT_DIR'),
         help="""Folder in which the artifacts will be stored. Defaults to EXEKALL_ARTIFACT_DIR env var.""")
 
-    run_parser.add_argument('--load-db', action='append',
+    add_argument(run_parser, '--load-db', action='append',
         default=[],
         help="""Reload a database to use some of its objects. The DB and its artifact directory will be merged in the produced DB at the end of the execution, to form a self-contained artifact directory.""")
 
-    run_parser.add_argument('--load-type', action='append',
-        metavar='LOAD_TYPE_PATTERN',
+    add_argument(run_parser, '--load-type', action='append',
+        metavar='TYPE_PATTERN',
         default=[],
         help="""Load the (indirect) instances of the given class from the database instead of the root objects.""")
 
     uuid_group = run_parser.add_mutually_exclusive_group()
 
-    uuid_group.add_argument('--load-uuid', action='append',
+    add_argument(uuid_group, '--load-uuid', action='append',
         default=[],
         help="""Load the given UUID from the database.""")
 
-    uuid_group.add_argument('--replay',
+    add_argument(uuid_group, '--replay',
         help="""Replay the execution of the given UUID, loading as much prerequisite from the DB as possible.""")
 
     # Load the parameters that were used to compute the value with the given
     # UUID from the database. This can be used as a more flexible form of
     # --replay that does not imply restricting the selection
-    uuid_group.add_argument('--load-uuid-args',
+    add_argument(uuid_group, '--load-uuid-args',
         help=argparse.SUPPRESS)
 
-    run_parser.add_argument('--restrict', action='append',
-        metavar='RESTRICT_PATTERN',
+    add_argument(run_parser, '--restrict', action='append',
+        metavar='CALLABLE_PATTERN',
         default=[],
         help="""Callable names patterns. Types produced by these callables will only be produced by these (other callables will be excluded).""")
 
-    run_parser.add_argument('--forbid', action='append',
-        metavar='FORBID_PATTERN',
+    add_argument(run_parser, '--forbid', action='append',
+        metavar='TYPE_PATTERN',
         default=[],
         help="""Fully qualified type names patterns. Callable returning these types or any subclass will not be called.""")
 
-    run_parser.add_argument('--allow', action='append',
-        metavar='ALLOW_PATTERN',
+    add_argument(run_parser, '--allow', action='append',
+        metavar='CALLABLE_PATTERN',
         default=[],
         help="""Allow using callable with a fully qualified name matching these patterns, even if they have been not selected for various reasons.""")
 
     goal_group = run_parser.add_mutually_exclusive_group()
-    goal_group.add_argument('--goal', action='append',
-        metavar='GOAL_PATTERN',
+    add_argument(goal_group, '--goal', action='append',
+        metavar='TYPE_PATTERN',
         default=[],
         help="""Compute expressions leading to an instance of a class with name matching this pattern (or a subclass of it).""")
 
-    goal_group.add_argument('--callable-goal', action='append',
-        metavar='CALLABLE_GOAL_PATTERN',
+    add_argument(goal_group, '--callable-goal', action='append',
+        metavar='CALLABLE_PATTERN',
         default=[],
         help="""Compute expressions ending with a callable which name is matching this pattern.""")
 
-    run_parser.add_argument('--sweep', nargs=5, action='append', default=[],
+    add_argument(run_parser, '--sweep', nargs=5, action='append', default=[],
         metavar=('CALLABLE_PATTERN', 'PARAM', 'START', 'STOP', 'STEP'),
         help="""Parametric sweep on a function parameter. It needs five fields:
     * pattern matching qualified name of the callable
@@ -314,21 +318,22 @@ PATTERNS
     * stop value
     * step size.""")
 
-    run_parser.add_argument('--template-scripts', metavar='SCRIPT_FOLDER',
+    add_argument(run_parser, '--template-scripts', metavar='SCRIPT_FOLDER',
         help="""Only create the template scripts of the expressions without running them.""")
 
-    run_parser.add_argument('--adaptor',
+    add_argument(run_parser, '--adaptor',
         help="""Adaptor to use from the customization module, if there is more than one to choose from.""")
 
-    run_parser.add_argument('-n', type=int,
+    add_argument(run_parser, '-n', type=int,
         default=1,
         help="""Run the tests for a number of iterations.""")
 
-    run_parser.add_argument('--share', action='append',
+    add_argument(run_parser, '--share', action='append',
+        metavar='TYPE_PATTERN',
         default=[],
         help="""Class name pattern to share between multiple iterations.""")
 
-    run_parser.add_argument('--random-order', action='store_true',
+    add_argument(run_parser, '--random-order', action='store_true',
         help="""Run the expressions in a random order, instead of sorting by name.""")
 
 
@@ -336,29 +341,33 @@ PATTERNS
     description="""
 Merge artifact directories of "exekall run" executions.
 
-By default, it will use hardlinks instead of copies to improve speed and avoid
-eating up large amount of space, but that means that artifact directories
-should be treated as read-only.
+By default, it will use hardlinks instead of copies to improve speed and
+avoid eating up large amount of space, but that means that artifact
+directories should be treated as read-only.
     """,
     formatter_class=argparse.RawTextHelpFormatter)
 
-    merge_parser.add_argument('artifact_dirs', nargs='+',
+    add_argument(merge_parser, 'artifact_dirs', nargs='+',
         help="""Artifact directories created using "exekall run", or value databases to merge.""")
 
-    merge_parser.add_argument('-o', '--output', required=True,
+    add_argument(merge_parser, '-o', '--output', required=True,
         help="""Output merged artifacts directory or value database.""")
 
-    merge_parser.add_argument('--copy', action='store_true',
+    add_argument(merge_parser, '--copy', action='store_true',
         help="""Force copying files, instead of using hardlinks.""")
 
 
     compare_parser = subparsers.add_parser('compare',
     description="""
 Compare two DBs produced by exekall run.
+
+Note that the adaptor in the customization module recorded in the database
+is able to add more parameters to ``exekall compare``. In order to get the
+complete set of options, please run ``exekall compare DB1 DB2 --help``.
     """,
     formatter_class=argparse.RawTextHelpFormatter)
 
-    compare_parser.add_argument('db', nargs=2,
+    add_argument(compare_parser, 'db', nargs=2,
         help="""DBs created using exekall run to compare.""")
 
     # Avoid showing help message on the incomplete parser. Instead, we carry on
@@ -666,7 +675,7 @@ def do_run(args, parser, run_parser, argv):
     # Get the prebuilt operators from the adaptor
     else:
         db_list = []
-        op_set.update(adaptor.get_prebuilt_set())
+        op_set.update(adaptor.get_prebuilt_op_set())
 
     # Force some parameter values to be provided with a specific callable
     patch_map = build_patch_map(args.sweep, op_set)
@@ -780,14 +789,14 @@ def do_run(args, parser, run_parser, argv):
     if rst_expr_list:
         id_kwargs['style'] = 'rst'
         for expr in expr_list:
-            out(expr.get_id(**id_kwargs))
+           out('* {}'.format(expr.get_id(**id_kwargs)))
     else:
         out('The following expressions will be executed:\n')
         for expr in expr_list:
             out(expr.get_id(**id_kwargs))
 
             if verbose >= 2:
-                out(expr.get_structure() + '\n')
+                out(expr.format_structure() + '\n')
 
         formatted_out = adaptor.format_expr_list(expr_list, verbose=verbose)
         if formatted_out:
@@ -879,8 +888,6 @@ def exec_expr_list(iteration_expr_list, adaptor, artifact_dir, testsession_uuid,
         data['artifact_dir'] = artifact_dir
         data['expr_artifact_dir'] = expr_artifact_dir
 
-        adaptor.update_expr_data(data)
-
         with (expr_artifact_dir/'UUID').open('wt') as f:
             f.write(expr.uuid + '\n')
 
@@ -893,7 +900,7 @@ def exec_expr_list(iteration_expr_list, adaptor, artifact_dir, testsession_uuid,
                 with_tags=False,
                 full_qual=True,
             ) + '\n\n')
-            f.write(expr.get_structure() + '\n')
+            f.write(expr.format_structure() + '\n')
 
         is_svg, dot_output = utils.render_graphviz(expr)
         graphviz_path = expr_artifact_dir/'STRUCTURE.{}'.format(
@@ -902,7 +909,7 @@ def exec_expr_list(iteration_expr_list, adaptor, artifact_dir, testsession_uuid,
         with graphviz_path.open('wt', encoding='utf-8') as f:
             f.write(dot_output)
 
-        with (expr_artifact_dir/'TESTCASE_TEMPLATE.py').open(
+        with (expr_artifact_dir/'EXPRESSION_TEMPLATE.py').open(
             'wt', encoding='utf-8'
         ) as f:
             f.write(
@@ -1018,7 +1025,7 @@ def exec_expr_list(iteration_expr_list, adaptor, artifact_dir, testsession_uuid,
                     prefix=prefix,
                 ))
 
-                out(adaptor.result_str(result))
+                out(adaptor.format_result(result))
                 result_list.append(result)
 
 
@@ -1029,7 +1036,7 @@ def exec_expr_list(iteration_expr_list, adaptor, artifact_dir, testsession_uuid,
             adaptor.finalize_expr(expr)
 
             # Dump the reproducer script
-            with (expr_artifact_dir/'TESTCASE.py').open('wt', encoding='utf-8') as f:
+            with (expr_artifact_dir/'EXPRESSION.py').open('wt', encoding='utf-8') as f:
                 f.write(
                     expr.get_script(
                         prefix = 'expr',
diff --git a/tools/exekall/exekall/utils.py b/tools/exekall/exekall/utils.py
index 8b0305d8e3c02cb81a56b6bf1580e9d3c66d32ec..8ae1c5324640f153bc7eda2fbfe55914f031e36e 100644
--- a/tools/exekall/exekall/utils.py
+++ b/tools/exekall/exekall/utils.py
@@ -27,6 +27,12 @@ import exekall.engine as engine
 from exekall._utils import *
 
 def get_callable_set(module_set, verbose=False):
+    """
+    Get the set of callables defined in all modules of ``module_set``.
+
+    :param module_set: Set of modules to scan.
+    :type module_set: set(types.ModuleType)
+    """
     # We keep the search local to the packages these modules are defined in, to
     # avoid getting a huge set of uninteresting callables.
     package_set = {
@@ -103,9 +109,29 @@ def _get_callable_set(module, visited_obj_set, verbose):
                 callable_pool.add(callable_)
     return callable_pool
 
-def sweep_number(
-    callable_, param,
-    start, stop=None, step=1):
+def sweep_number(callable_, param, start, stop=None, step=1):
+    """
+    Used to generate a stream of numbers to feed to a callable.
+
+    :param callable_: Callable the numbers will be used by.
+    :type callable_: collections.abc.Callable
+
+    :param param: Name of the parameter of the callable the numbers will be
+        providing values for.
+    :type param: str
+
+    :param start: Starting value.
+    :type start: float
+
+    :param stop: End value (inclusive)
+    :type stop: float
+
+    :param step: Increment step.
+    :type step: float
+
+    The type used will either be one that is annotated on the callable, or
+    the type of the value given as ``start``.
+    """
 
     step = step if step > 0 else 1
 
@@ -126,6 +152,9 @@ def sweep_number(
         i += step
 
 def get_method_class(function):
+    """
+    Get the class in which a ``function`` is defined.
+    """
     # Unbound instance methods
     if isinstance(function, engine.UnboundMethod):
         return function.cls
diff --git a/tools/exekall/exekall/valuedb.py b/tools/exekall/exekall/valuedb.py
new file mode 100644
index 0000000000000000000000000000000000000000..f019252560a9454ef243ec295ae8032334ade98d
--- /dev/null
+++ b/tools/exekall/exekall/valuedb.py
@@ -0,0 +1,26 @@
+#! /usr/bin/env python3
+# SPDX-License-Identifier: Apache-2.0
+#
+# Copyright (C) 2019, ARM Limited and contributors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"); you may
+# not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+# Re-export a stable subset of the engine's API that is meant to be used by
+# external code.
+from exekall.engine import (
+    ValueDB,
+    FrozenExprVal,
+    PrunedFrozVal,
+    FrozenExprValSeq,
+)
diff --git a/tools/scripts/travis_tests.sh b/tools/scripts/travis_tests.sh
index 9dca0792049b47d691030ce554c9eda632378ada..a9b75df514ad1021e44ebc9571c74cefc5852138 100755
--- a/tools/scripts/travis_tests.sh
+++ b/tools/scripts/travis_tests.sh
@@ -42,4 +42,13 @@ echo "Available LISA tests:"
 lisa-test --list
 
 echo "Starting documentation pedantic build ..."
-cd doc/ && ./pedantic_build.sh
+(cd doc/ && ./pedantic_build.sh)
+
+echo "Checking that the man pages are up to date ..."
+
+if ! git diff --exit-code doc/man1/; then
+    echo "Please regenerate man pages in doc/man1 and commit them"
+    exit 1
+fi
+
+