diff --git a/.gitignore b/.gitignore
index 20cc9750b..a55d9e254 100644
--- a/.gitignore
+++ b/.gitignore
@@ -43,6 +43,7 @@ output/*/index.html
 
 # Sphinx
 doc/build
+doc/source/api
 
 # pbr generates these
 AUTHORS
diff --git a/doc/source/dev/plugins.rst b/doc/source/dev/plugins.rst
index 9d7b3f5b5..ad82dcd95 100644
--- a/doc/source/dev/plugins.rst
+++ b/doc/source/dev/plugins.rst
@@ -75,6 +75,7 @@ should implement:
 
 .. autoclass:: BaseStrategy
     :members:
+    :noindex:
 
 
 Add a new entry point
@@ -169,6 +170,7 @@ Here below is the abstract ``BaseClusterHistory`` class of the Helper.
 
 .. autoclass:: BaseClusterHistory
     :members:
+    :noindex:
 
 
 The following snippet code shows how to create a Cluster History class:
diff --git a/doc/source/glossary.rst b/doc/source/glossary.rst
index c0b9532c3..e037e856c 100644
--- a/doc/source/glossary.rst
+++ b/doc/source/glossary.rst
@@ -264,13 +264,6 @@ Please, read `the official OpenStack definition of a Project <http://docs.openst
 
 .. _primitive_definition:
 
-Primitive
-=========
-
-.. watcher-term:: watcher.applier.primitives.base
-
-.. _sla_definition:
-
 SLA
 ===
 
diff --git a/doc/source/index.rst b/doc/source/index.rst
index ef53ef686..6e2bc06b8 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -71,6 +71,15 @@ Watcher Manual Pages
 
    man/*
 
+.. # NOTE(mriedem): This is the section where we hide things that we don't
+   # actually want in the table of contents but sphinx build would fail if
+   # they aren't in the toctree somewhere. For example, we hide api/autoindex
+   # since that's already covered with modindex below.
+.. toctree::
+   :hidden:
+
+   api/autoindex
+
 
 Indices and tables
 ==================
diff --git a/setup.cfg b/setup.cfg
index 812e8309e..bb1d7b5b1 100644
--- a/setup.cfg
+++ b/setup.cfg
@@ -62,6 +62,16 @@ watcher_workflow_engines =
 watcher_planners =
     default  = watcher.decision_engine.planner.default:DefaultPlanner
 
+[pbr]
+autodoc_index_modules = True
+autodoc_exclude_modules =
+    watcher.db.sqlalchemy.alembic.env
+    watcher.db.sqlalchemy.alembic.versions.*
+    watcher.tests.*
+    watcher_tempest_plugin.*
+    watcher.doc
+
+
 [build_sphinx]
 source-dir = doc/source
 build-dir = doc/build
diff --git a/tox.ini b/tox.ini
index 0681c7666..e9a365ff0 100644
--- a/tox.ini
+++ b/tox.ini
@@ -20,12 +20,14 @@ commands =
 commands = flake8
 
 [testenv:venv]
+setenv = PYTHONHASHSEED=0
 commands = {posargs}
 
 [testenv:cover]
 commands = python setup.py testr --coverage --omit="watcher/tests/*" --testr-args='{posargs}'
 
 [testenv:docs]
+setenv = PYTHONHASHSEED=0
 commands = python setup.py build_sphinx
 
 [testenv:debug]
diff --git a/watcher/common/ceilometer.py b/watcher/common/ceilometer.py
index 49f42f706..703733df4 100644
--- a/watcher/common/ceilometer.py
+++ b/watcher/common/ceilometer.py
@@ -49,12 +49,12 @@ class CeilometerClient(object):
         This query can be then used for querying resources, meters and
         statistics.
         :Parameters:
-          - `user_id`: user_id, has a priority over list of ids
-          - `tenant_id`: tenant_id, has a priority over list of ids
-          - `resource_id`: resource_id, has a priority over list of ids
-          - `user_ids`: list of user_ids
-          - `tenant_ids`: list of tenant_ids
-          - `resource_ids`: list of resource_ids
+        - `user_id`: user_id, has a priority over list of ids
+        - `tenant_id`: tenant_id, has a priority over list of ids
+        - `resource_id`: resource_id, has a priority over list of ids
+        - `user_ids`: list of user_ids
+        - `tenant_ids`: list of tenant_ids
+        - `resource_ids`: list of resource_ids
         """
 
         user_ids = user_ids or []
diff --git a/watcher/common/nova.py b/watcher/common/nova.py
index c5d0ffccb..58fcc09d5 100644
--- a/watcher/common/nova.py
+++ b/watcher/common/nova.py
@@ -76,9 +76,9 @@ class NovaClient(object):
 
         :param instance_id: the unique id of the instance to migrate.
         :param keep_original_image_name: flag indicating whether the
-        image name from which the original instance was built must be
-        used as the name of the intermediate image used for migration.
-        If this flag is False, a temporary image name is built
+            image name from which the original instance was built must be
+            used as the name of the intermediate image used for migration.
+            If this flag is False, a temporary image name is built
         """
 
         new_image_name = ""
@@ -438,13 +438,13 @@ class NovaClient(object):
 
         It waits for this image to be in 'active' state before returning.
         It returns the unique UUID of the created image if successful,
-        None otherwise
+        None otherwise.
 
         :param instance_id: the uniqueid of
-        the instance to backup as an image.
+            the instance to backup as an image.
         :param image_name: the name of the image to create.
         :param metadata: a dictionary containing the list of
-        key-value pairs to associate to the image as metadata.
+            key-value pairs to associate to the image as metadata.
         """
         if self.glance is None:
             glance_endpoint = self.keystone. \
@@ -568,7 +568,7 @@ class NovaClient(object):
 
         :param instance: instance object.
         :param status_list: tuple containing the list of
-        status we are waiting for
+            status we are waiting for
         :param retry: how many times to retry
         :param sleep: seconds to sleep between the retries
         """
diff --git a/watcher/decision_engine/planner/base.py b/watcher/decision_engine/planner/base.py
index 13255baf0..1504617ae 100644
--- a/watcher/decision_engine/planner/base.py
+++ b/watcher/decision_engine/planner/base.py
@@ -53,8 +53,8 @@ class BasePlanner(object):
         :param solution: the solution given by the strategy to
         :param audit_uuid: the audit uuid
         :return: ActionPlan ordered sequence of change requests
-        such that all security, dependency,
-        and performance requirements are met.
+            such that all security, dependency, and performance
+            requirements are met.
         """
         # example: directed acyclic graph
         raise NotImplementedError()
diff --git a/watcher/decision_engine/solution/base.py b/watcher/decision_engine/solution/base.py
index 5bdb03a86..ff107cbb9 100644
--- a/watcher/decision_engine/solution/base.py
+++ b/watcher/decision_engine/solution/base.py
@@ -92,13 +92,13 @@ class BaseSolution(object):
         """Add a new Action in the Action Plan
 
         :param action_type: the unique id of an action type defined in
-        entry point 'watcher_actions'
+            entry point 'watcher_actions'
         :param applies_to: the unique id of the resource to which the
-        `Action` applies.
+            `Action` applies.
         :param input_parameters: An array of input parameters provided as
-         key-value pairs of strings.
-         Each key-pair contains names and values that match what was previously
-         defined in the `Action` type schema.
+            key-value pairs of strings. Each key-pair contains names and
+            values that match what was previously defined in the `Action`
+            type schema.
         """
         raise NotImplementedError()