enhance documentation

- flatten hierarchy (some links do not work when using folders)
+ fix a bug with the redorder flag in Override
+ allow removal of parameters
+ clean description using inspect.cleandoc

Change-Id: I3dde4f4cb29c46e8a21014f1fad7aa3ad610a1bf

doc/source/conf.py

@@ -89,9 +89,10 @@ pygments_style = 'sphinx'
 # If true, `todo` and `todoList` produce output, else they produce nothing.
 todo_include_todos = True
 
-# sort by source instead of alphabetic
-autodoc_member_order = 'bysource'
-
+autodoc_default_options = {
+    'member-order': 'bysource',
+    'show-inheritance': True,
+}
 default_role = 'any'
 
 # -- Options for HTML output ----------------------------------------------
@@ -99,9 +100,19 @@ default_role = 'any'
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-#import sphinx_rtd_theme
-#html_theme = 'sphinx_rtd_theme'
-html_theme = 'alabaster'
+if False:  # alabaster
+    html_theme = 'alabaster'
+    # Theme options are theme-specific and customize the look and feel of a theme
+    # further.  For a list of options available for each theme, see the
+    # documentation.
+    #
+    html_theme_options = {
+        'page_width': '100%',
+        'fixed_sidebar': True,
+    }
+else:
+    import sphinx_rtd_theme
+    html_theme = 'sphinx_rtd_theme'
 
 # If not None, a 'Last updated on:' timestamp is inserted at every page
 # bottom, using the given strftime format.
@@ -110,14 +121,6 @@ html_theme = 'alabaster'
 html_last_updated_fmt = '%Y-%m-%d %H:%M'
 
 
-# Theme options are theme-specific and customize the look and feel of a theme
-# further.  For a list of options available for each theme, see the
-# documentation.
-#
-html_theme_options = {
-    'page_width': '100%',
-    'fixed_sidebar': True,
-}
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,