diff --git a/doc/source/user/usage.rst b/doc/source/user/usage.rst
index 1b2d9961..2fe883c0 100644
--- a/doc/source/user/usage.rst
+++ b/doc/source/user/usage.rst
@@ -9,7 +9,7 @@ Session Handling
 
 Session handling is achieved using the :mod:`oslo_db.sqlalchemy.enginefacade`
 system.   This module presents a function decorator as well as a
-context manager approach to delivering :class:`.Session` as well as
+context manager approach to delivering :class:`.session.Session` as well as
 :class:`.Connection` objects to a function or block.
 
 Both calling styles require the use of a context object.   This object may
@@ -76,7 +76,7 @@ decorator.   Each function must receive the context argument:
         some_writer_api_function(context, 5, 10)
 
 
-``connection`` modifier can be used when a :class:`.Session` object is not
+``connection`` modifier can be used when a :class:`.session.Session` object is not
 needed, e.g. when `SQLAlchemy Core <http://docs.sqlalchemy.org/en/latest/core/>`_
 is preferred:
 
diff --git a/oslo_db/sqlalchemy/session.py b/oslo_db/sqlalchemy/session.py
index bb3616f8..5e373635 100644
--- a/oslo_db/sqlalchemy/session.py
+++ b/oslo_db/sqlalchemy/session.py
@@ -90,8 +90,8 @@ Recommended ways to use sessions within this framework:
 
   .. code-block:: sql
 
-    UPDATE bar SET bar = ${newbar}
-        WHERE id=(SELECT bar_id FROM foo WHERE id = ${foo_id} LIMIT 1);
+    UPDATE bar SET bar = '${newbar}'
+        WHERE id=(SELECT bar_id FROM foo WHERE id = '${foo_id}' LIMIT 1);
 
   .. note:: `create_duplicate_foo` is a trivially simple example of catching an
      exception while using a savepoint. Here we create two duplicate
diff --git a/oslo_db/sqlalchemy/test_migrations.py b/oslo_db/sqlalchemy/test_migrations.py
index 09e61f84..d650025a 100644
--- a/oslo_db/sqlalchemy/test_migrations.py
+++ b/oslo_db/sqlalchemy/test_migrations.py
@@ -45,7 +45,7 @@ class WalkVersionsMixin(object):
     abstract class mixin. `INIT_VERSION`, `REPOSITORY` and `migration_api`
     attributes must be implemented in subclasses.
 
-    .. _auxiliary-dynamic-methods: Auxiliary Methods
+    .. _auxiliary-dynamic-methods:
 
     Auxiliary Methods:
 
@@ -214,7 +214,7 @@ class WalkVersionsMixin(object):
         :type version: str
         :keyword with_data: Whether to verify the absence of changes from
             migration(s) being downgraded, see
-            :ref:`auxiliary-dynamic-methods <Auxiliary Methods>`.
+            :ref:`Auxiliary Methods <auxiliary-dynamic-methods>`.
         :type with_data: Bool
         """
 
@@ -246,7 +246,7 @@ class WalkVersionsMixin(object):
         :param version: id of revision to upgrade.
         :type version: str
         :keyword with_data: Whether to verify the applied changes with data,
-            see :ref:`auxiliary-dynamic-methods <Auxiliary Methods>`.
+            see :ref:`Auxiliary Methods <auxiliary-dynamic-methods>`.
         :type with_data: Bool
         """
         # NOTE(sdague): try block is here because it's impossible to debug
diff --git a/setup.cfg b/setup.cfg
index 9f3ea27a..c187de99 100644
--- a/setup.cfg
+++ b/setup.cfg
@@ -71,6 +71,7 @@ universal = 1
 source-dir = doc/source
 build-dir = doc/build
 all_files = 1
+warning-is-error = 1
 
 [upload_sphinx]
 upload-dir = doc/build/html
@@ -90,7 +91,6 @@ mapping_file = babel.cfg
 output_file = oslo_db/locale/oslo_db.pot
 
 [pbr]
-warnerrors = True
 autodoc_index_modules = True
 api_doc_dir = reference/api
 autodoc_exclude_modules =