Document bindep usage

We use bindep to install our requirements, explain how to use it.

Also, add the bindep tox environment.

See also
https://docs.openstack.org/infra/manual/drivers.html#package-requirements

Change-Id: Ief208e5649223d9d3577ee0a30afdc7db35a86a9

README.rst

@@ -64,6 +64,12 @@ To build a specific guide with a PDF file, add a ``-pdf`` option like::
 The generated PDF file will be copied to the root directory of the
 generated HTML documentation.
 
+To install all requirements to execute the commands above check the
+output of the ``bindep`` command, it reports missing requirements for
+all build targets::
+
+    $ tox -e bindep
+
 
 Testing of changes and building of the manual
 =============================================

doc/contributor-guide/source/docs-builds.rst

@@ -13,37 +13,41 @@ file with specific sections that run jobs using the `Tox
 <https://tox.readthedocs.org/en/latest/>`_ tool, a virtualenv-based
 automation of test activities.
 
-Tox prerequisites and installation
-----------------------------------
-
-**Install the prerequisites for Tox:**
+Install dependencies for building documentation
+-----------------------------------------------
 
 * On Ubuntu or Debian:
 
   .. code-block:: console
 
-     # apt-get install gcc gettext python-dev libxml2-dev libxslt1-dev \
-       zlib1g-dev
-
-  You may need to use :command:`pip install` for some packages.
+     # apt-get install python-pip
+     # pip install tox
+     $ tox -e bindep
+     # apt-get install <indicated missing package names>
 
 * On RHEL or CentOS including Fedora:
 
   .. code-block:: console
 
-     # yum install gcc python-devel libxml2-devel libxslt-devel
+     # yum install python-pip
+     # pip install tox
+     $ tox -e bindep
+     # yum install <indicated missing package names>
 
 * On openSUSE or SUSE Linux Enterprise:
 
   .. code-block:: console
 
-     # zypper install gcc python-devel libxml2-devel libxslt-devel
+     # zypper in python-pip
+     # pip install tox
+     $ tox -e bindep
+     # zypper in <indicated missing package names>
 
-**Install python-tox:**
+.. note::
 
-.. code-block:: console
-
-   # pip install tox
+   This will install all required packages for building both RST and
+   PDF files. If you do not build PDF files, you do not need to install
+   the ``texlive`` packages.
 
 Build workflow
 --------------

tox.ini

@@ -112,6 +112,17 @@ commands = {toxinidir}/tools/generatepot-rst.sh openstack-manuals 1 {posargs}
 commands =
   sphinx-build -a -E -W -d releasenotes/build/doctrees -b html releasenotes/source releasenotes/build/html
 
+[testenv:bindep]
+# Do not install any requirements. We want this to be fast and work even if
+# system dependencies are missing, since it's used to tell you what system
+# dependencies are missing! This also means that bindep must be installed
+# separately, outside of the requirements files, and develop mode disabled
+# explicitly to avoid unnecessarily installing the checked-out repo too (this
+# further relies on "tox.skipsdist = True" above).
+deps = bindep
+commands = bindep test
+usedevelop = False
+
 [doc8]
 # Settings for doc8:
 # Ignore target directories