Merge "Document Graphviz as a prerequisite of the firstapp doc"

README.rst

@@ -20,8 +20,7 @@ In addition to these documents, this repository contains:
 Prerequisites
 =============
 
-To build the documentation, you must install
+To build the documentation, you must install `Apache Maven <http://maven.apache.org/>`_.
-`Apache Maven <http://maven.apache.org/>`_.
 
 To install Maven 3 for Ubuntu 12.04 or later or Debian 7 ("wheezy") or later::
 
@@ -37,6 +36,28 @@ To install Tox for Ubuntu 14.04 or later::
 
     apt-get install python-tox python-dev libxml2-dev libxslt1-dev
 
+"Writing your First OpenStack Application" tutorial
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To build the "Writing your first OpenStack application" tutorial, you must
+install `Graphviz <http://www.graphviz.org/>`_.
+
+To install Graphviz for Ubuntu 12.04 or later or Debian 7 ("wheezy") or later::
+
+    apt-get install graphviz
+
+On Fedora 22 and later::
+
+    dnf install graphviz
+
+On openSUSE::
+
+    zypper install graphviz
+
+On Mac OSX with Homebrew installed::
+
+    brew install graphviz
+
 Build and update API docs
 =========================
 
@@ -122,9 +143,9 @@ Our community welcomes everyone who is interested in open source cloud
 computing and encourages you to join the `OpenStack Foundation <http://www.openstack.org/join>`_.
 
 The best way to get involved with the community is to talk with others online
-or at a meetup and offer contributions through our processes,
+or at a meetup and offer contributions through our processes, the
-the `OpenStack wiki <http://wiki.openstack.org>`_, blogs, or
+`OpenStack wiki <http://wiki.openstack.org>`_, blogs, or on IRC at ``#openstack`` on
-on IRC at ``#openstack`` on ``irc.freenode.net``.
+``irc.freenode.net``.
 
 We welcome all types of contributions, from blueprint designs to documentation
 to testing to deployment scripts.

firstapp/README.rst

@@ -23,23 +23,27 @@ The :code:`/source` directory contains the tutorial documentation as
 `reStructuredText <http://docutils.sourceforge.net/rst.html>`_ (RST). The
 documentation is built with `Sphinx <http://sphinx-doc.org/>`_.
 
-The RST source includes conditional output logic, so specifying::
+The RST source includes conditional output logic. To invoke
+:code:`sphinx-build` with :code:`-t libcloud`::
 
   tox -e firstapp-libcloud
 
-will invoke :code:`sphinx-build` with :code:`-t libcloud`, meaning sections
+Only the sections marked :code:`.. only:: libcloud` in the RST are built.
-marked :code:`.. only:: libcloud` in the RST are built, while others
-are not built.
 
-To build the documentation, you need Sphinx and the OpenStack
+To build the documentation, you must install `Sphinx <http://sphinx-doc.org/>`_
-docs.openstack.org Sphinx Theme (openstackdocstheme). When you invoke tox,
+and the
-these dependencies are automatically pulled in from the top-level :code:`test-requirements.txt`.
+`OpenStack docs.openstack.org Sphinx theme (openstackdocstheme) <https://pypi.python.org/pypi/openstackdocstheme>`_.
+
+When you invoke tox, these dependencies are automatically pulled in from the
+top-level :code:`test-requirements.txt`.
+
+You must also install `Graphviz <http://www.graphviz.org/>`_ on your build system.
 
 /samples
 ~~~~~~~~
 
-The code samples provided in the guide are sourced from files in this
+The code samples in the guide are located in this directory. The code samples
-directory. Each SDK has its own subdirectory.
+for each SDK are located in separate subdirectories.
 
 /build-libcloud
 ~~~~~~~~~~~~~~~