diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst
index c458b441..a6a308c4 100644
--- a/CONTRIBUTING.rst
+++ b/CONTRIBUTING.rst
@@ -1,3 +1,7 @@
+=================
+How to contribute
+=================
+
 If you would like to contribute to the development of OpenStack,
 you must follow the steps in the "If you're a developer, start here"
 section of this page:
@@ -14,4 +18,4 @@ Pull requests submitted through GitHub will be ignored.
 
 Bugs should be filed on Launchpad, not GitHub:
 
-   https://bugs.launchpad.net/oslo.db
\ No newline at end of file
+   https://bugs.launchpad.net/oslo.db
diff --git a/README.rst b/README.rst
index b87094bb..d5e433ca 100644
--- a/README.rst
+++ b/README.rst
@@ -1,5 +1,5 @@
 ===================================
-oslo.db
+Overview
 ===================================
 
 oslo.db library
@@ -7,4 +7,4 @@ oslo.db library
 * Free software: Apache license
 * Documentation: http://docs.openstack.org/developer/oslo.db
 * Source: http://git.openstack.org/cgit/openstack/oslo.db
-* Bugs: http://bugs.launchpad.net/oslo
\ No newline at end of file
+* Bugs: http://bugs.launchpad.net/oslo
diff --git a/doc/source/conf.py b/doc/source/conf.py
index 510e579f..b79e4059 100755
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -30,6 +30,14 @@ extensions = [
 # text edit cycles.
 # execute "export SPHINX_DEBUG=1" in your terminal to disable
 
+# A list of glob-style patterns that should be excluded when looking for source
+# files.
+exclude_patterns = [
+    'api/setup.rst', # workaround for https://launchpad.net/bugs/1260495
+    'api/tests.*',  # avoid of docs generation from tests
+    'api/oslo.db.openstack.common.*',  # skip common modules
+]
+
 # The suffix of source filenames.
 source_suffix = '.rst'
 
@@ -72,4 +80,4 @@ latex_documents = [
 ]
 
 # Example configuration for intersphinx: refer to the Python standard library.
-#intersphinx_mapping = {'http://docs.python.org/': None}
\ No newline at end of file
+#intersphinx_mapping = {'http://docs.python.org/': None}
diff --git a/doc/source/index.rst b/doc/source/index.rst
index 10db04b7..037fe74a 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -1,7 +1,11 @@
-Welcome to oslo.db's documentation!
-===================================
+Welcome to oslo.db documentation!
+=================================
+
+The Oslo database handling library. Provides database connectivity
+to the different backends and helper utils.
 
 Contents:
+---------
 
 .. toctree::
    :maxdepth: 2
@@ -12,7 +16,7 @@ Contents:
    contributing
 
 Indices and tables
-==================
+------------------
 
 * :ref:`genindex`
 * :ref:`modindex`
diff --git a/doc/source/readme.rst b/doc/source/readme.rst
index 6b2b3ec6..a6210d3d 100644
--- a/doc/source/readme.rst
+++ b/doc/source/readme.rst
@@ -1 +1 @@
-.. include:: ../README.rst
\ No newline at end of file
+.. include:: ../../README.rst
diff --git a/setup.cfg b/setup.cfg
index 3062d81e..78097e83 100644
--- a/setup.cfg
+++ b/setup.cfg
@@ -54,3 +54,9 @@ input_file = oslo.db/locale/oslo.db.pot
 keywords = _ gettext ngettext l_ lazy_gettext
 mapping_file = babel.cfg
 output_file = oslo.db/locale/oslo.db.pot
+
+[pbr]
+# NOTE(viktors): uncomment ``warnerrors`` line, when setup.cfg we then
+# want to treat sphinx warnings as errors
+# warnerrors = True
+autodoc_index_modules = True
diff --git a/tox.ini b/tox.ini
index 1c483a63..fef9a35c 100644
--- a/tox.ini
+++ b/tox.ini
@@ -26,6 +26,10 @@ commands = {posargs}
 [testenv:cover]
 commands = python setup.py testr --coverage --testr-args='{posargs}'
 
+[testenv:docs]
+commands =
+    python setup.py build_sphinx
+
 [flake8]
 # H803 skipped on purpose per list discussion.
 # E123, E125 skipped as they are invalid PEP-8.