From b06db69322e8cf644d592ecbb481f9ec89c91da4 Mon Sep 17 00:00:00 2001
From: Andreas Jaeger <aj@suse.com>
Date: Fri, 24 Feb 2017 13:17:49 +0000
Subject: [PATCH] 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                                   |  6 ++++
 doc/contributor-guide/source/docs-builds.rst | 32 +++++++++++---------
 tox.ini                                      | 11 +++++++
 3 files changed, 35 insertions(+), 14 deletions(-)

diff --git a/README.rst b/README.rst
index cceb03f719..a1110ce4e1 100644
--- a/README.rst
+++ b/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
 =============================================
diff --git a/doc/contributor-guide/source/docs-builds.rst b/doc/contributor-guide/source/docs-builds.rst
index 35a9882a7f..07babb5f3f 100644
--- a/doc/contributor-guide/source/docs-builds.rst
+++ b/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
 --------------
diff --git a/tox.ini b/tox.ini
index 93bdf88545..db9eaf8543 100644
--- a/tox.ini
+++ b/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