doc: update doc building README instructions

Updated the README.rst describing how to setup the document building
tools on an Ubuntu system (listing versions of tools) and how to
generate a local copy of the html documentation.

Change-Id: I4ca1a99a48709b2313c479487abf42480c5af035
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>

1 files changed, 62 insertions, 32 deletions

diff --git a/doc/README.rst b/doc/README.rst
index 9b2912a5e..3dcbc4a08 100644
--- a/doc/README.rst
+++ b/doc/README.rst
@@ -16,68 +16,98 @@ designed to walk you through generating the Zephyr Project's documentation.
 Documentation Notes
 *******************
 
+Zephyr Project content is written using the reStructuredText markup language
+(.rst file extension) with Sphinx extensions, and processed using sphinx to
+create a formatted standalone website. Developers can view this content either
+in its raw form as .rst markup files, or you can generate the HTML content and view it
+with a web browser directly on your workstations drive. This same .rst
+content is also fed into the Zephyr Project'ns public website documentation area
+(with a different theme applied).
+
+You can read details about reStructuredText and about Sphinx extensions from
+their respective websites.
+
 The project's documentation currently comprises the following items:
 
-* An Installation Guide for Linux host systems
+* ReStructuredText source files used to generate documentation found at
+  https://zephyrproject.org/doc website. Most of the reStructuredText sources
+  are found in the ``/doc`` directory, but there are others stored within the
+  code source tree near their specific component (such as ``/samples`` and
+  ``/boards``)
 
-* A set of Collaboration Guidelines for the project.
+* Doxygen-generated material used to create all API-specific documents
+  also found at https://zephyrproject.org/doc
 
-* Doxygen output from the code base for all APIs.
+* Script-generated material for kernel configuration options based on kconfig
+  files found in the source code tree
 
-Installing the documentation processors
-***************************************
+* Additional material on https://wiki.zephyrproject.org
 
-Install the current version of ``Sphinx``, type:
+The reStructuredText files are processed by the Sphinx documentation system,
+and make use of the breathe extension for including the doxygen-generated API
+material.  Additional tools are required to generate the
+documentation locally, as described in the following sections.
 
-.. code-block:: bash
+Installing the documentation processors
+***************************************
 
-   $ git clone https://github.com/sphinx-doc/sphinx.git sphinx
+Our documentation processing has been tested to run with:
 
-   $ cd sphinx
+* Doxygen version 1.8.10 (and 1.8.11)
+* Sphinx version 1.4.4 (but not with 1.5.1)
+* Breathe version 4.4.0
+* docutils version 0.12 (0.13 has issues with Sphinx 1.4.4)
 
-   $ sudo -E python setup.py install
+Begin by cloning a copy of the git repository for the zephyr project and
+setting up your development environment as described in :ref:`getting_started`
+or specifically for Ubuntu in :ref:`installation_linux`.  (Be sure to
+export the environment variables ``ZEPHYR_GCC_VARIANT`` and
+``ZEPHYR_SDK_INSTALL_DIR`` as documented there.)
 
-   $ cd ..
+Here are a set of commands to install the documentation generations tools on
+Ubuntu:
 
-   $ git clone https://github.com/michaeljones/breathe.git breathe
 
-   $ cd breathe
+.. code-block:: bash
 
-   $ sudo -E python setup.py install
+   $ sudo apt-get install python-pip
+   $ pip install --upgrade pip
+   $ sudo apt-get install doxygen
+   $ pip install sphinx==1.4.4
+   $ sudo -H pip install breathe
+   $ sudo -H pip install sphinx-rtd-theme
 
-To install ReadTheDocs.org theme, use pip to install the python package:
+There is a known issue that causes docutils version 0.13 to fail with sphinx
+1.4.4.  Verify the version of docutils using:
 
 .. code-block:: bash
 
-   $ pip install sphinx_rtd_theme
+   $ pip show docutils
+
+If this shows you've got version 0.13 of docutils installed, you can install
+the working version of docutils with:
 
-If the above theme is installed, it will be used instead of the default theme.
+.. code-block:: bash
 
-.. note::
+   $ sudo -H pip install docutils==0.12
 
-   Make sure that ``Doxygen`` is installed in your system.
-   The installation of Doxygen is beyond the scope of this document.
 
 Running the Documentation Generators
 ************************************
 
-Assuming that the Zephyr Project tree with the doc directory is in
-``<ZEPHYR_BASE>``, type:
+The ``/doc`` directory in your cloned copy of zephyr project git repo has all the
+.rst source files, extra tools, and Makefile for generating a local copy of
+the Zephyr project's technical documentation.  Assuming the local Zephyr
+project copy is ``~/zephyr``, here are the commands to generate the html
+content locally:
 
 .. code-block:: bash
 
-   $ cd <ZEPHYR_BASE>
+   $ cd ~/zephyr
+   $ source zephyr-env.sh
    $ make htmldocs
 
-Find the output in ``<ZEPHYR_BASE>/doc/_build/html/index.html``
-
-Review the available formats with:
-
-.. code-block:: bash
-
-   $ make -C <ZEPHYR_BASE>/doc help
+The html output will be in ``~/zephyr/doc/_build/html/index.html``
 
-If you want the LaTeX PDF output, you need to install all the Latex
-packages first. That installation is beyond the scope of this document.
 
 .. _ReST documentation: http://sphinx-doc.org/rest.html