diff --git a/reference/project-testing-interface.rst b/reference/project-testing-interface.rst
index 057608f48..75fe1ebc8 100644
--- a/reference/project-testing-interface.rst
+++ b/reference/project-testing-interface.rst
@@ -55,17 +55,32 @@ To support documentation generation, projects should:
   ``doc`` tag.
 * Depend on ``openstackdocstheme`` for documentation and configure it to be
   used in ``doc/source/conf.py``.
+* Have a ``docs`` environment set up in a ``tox.ini`` file within the
+  repository.
 
-Assuming requirements have been properly installed as indicated by
-``doc/requirements.txt`` and ``bindep.txt``, the following command should
-work with no additional setup and should result in the documentation being
-emitted into ``doc/build/html``.
+Assuming non-Python requirements have been properly installed as
+indicated by ``bindep.txt``, the following command should work with no
+additional setup and should result in the documentation being emitted
+into ``doc/build/html``.
 
 .. code-block:: bash
 
-  sphinx-build -b html doc/source doc/build/html
+  tox -e docs
 
-Language specific instructions supplement these and are in addition to them.
+.. note::
+
+   We strongly discourage project teams from adding commands to the
+   ``docs`` environment beyond:
+
+   .. code-block:: bash
+
+      sphinx-build -W -b html doc/source doc/build/html
+
+   Additional logic needed around Sphinx generation should go into
+   Sphinx plugins.
+
+Language specific instructions supplement these and are in addition to
+them.
 
 Release Notes
 -------------
diff --git a/reference/pti/python.rst b/reference/pti/python.rst
index 6ba2b53b4..47fb6e038 100644
--- a/reference/pti/python.rst
+++ b/reference/pti/python.rst
@@ -148,22 +148,6 @@ dir should be the $project.pot file. For instance, for nova, there should be
 nova/locale/nova.pot. Babel commands should be configured out output their .mo
 files in to $project/locale as well.
 
-Documentation
--------------
-
-In addition to the normal PTI :ref:`pti-documentation` requirements, as a
-convenience for developers, it is recommended that projects provide
-a ``docs`` environment for tox that will run
-
-.. code-block:: bash
-
-  sphinx-build -b html doc/source doc/build
-
-The project infrastructure will not use ``tox -e docs`` to build the
-documentation. Therefore it is **STRONGLY** discouraged for people to put
-additional logic into the command section of that tox environment. Additional
-logic needed around Sphinx generation should go into Sphinx plugins.
-
 Release Notes
 -------------