docs: update the documentation and add some missing sections

[ci skip]

README.rst

@@ -31,7 +31,7 @@ Highlights of the framework
 
 Docs and Examples
 =================
-See `the docs <http://nucleic.github.io/enaml/docs>`_ and `examples <http://nucleic.github.io/enaml/docs/examples/index.html>`_ for more information.
+See `the docs <http://enaml.readthedocs.io/en/latest/index.html>`_ and `examples <http://enaml.readthedocs.io/en/latest/examples/index.html>`_ for more information.
 
 
 Also several talks on Enaml:

docs/Makefile

@@ -35,9 +35,11 @@ help:
 
 clean:
 	-rm -rf $(BUILDDIR)/*
-
-html: 
-	python source/examples/example_doc_generator.py
+
+examples:
+   python source/examples/example_doc_generator.py
+
+html:
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."

docs/make.bat

@@ -40,8 +40,11 @@ if "%1" == "clean" (
 	goto end
 )
 
+if "%1" == "examples" (
+   python source\examples\example_doc_generator.py
+)
+
 if "%1" == "html" (
-    python source\examples\example_doc_generator.py
 	%SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html
 	if errorlevel 1 exit /b 1
 	echo.

docs/source/dev_guides/index.rst

@@ -16,8 +16,7 @@ the framework see the :ref:`arch_ref`.
     stylesheets
 
 
-:doc:`stylesheets`
-------------------
+.. rubric::`stylesheets`
 
     Styles sheets are a powerful feature which allow the developer to
     customize the visual appearance of a view independent from the

docs/source/get_started/anatomy.rst

@@ -13,7 +13,7 @@ application.
 
     - For the motivations and background on Enaml, see the :doc:`introduction`.
 
-    - For connecting data models to the UI, see :doc:`models`.
+    - For connecting data models to the UI, see :doc:`syntax`.
 
     - For advanced articles on the Enaml language and framework,
       see the :doc:`/dev_guides/index`.
@@ -63,7 +63,7 @@ Elements are customized by binding data to their attributes. In the example,
 the ``text`` attributes of the ``Label`` elements and the ``title`` attribute
 of the ``PersonView`` element are assigned static string values, and the
 ``text`` attributes of the ``Field`` elements are bound to data in a data
-model. The specifics of data model binding are covered in :doc:`models`.
+model. The specifics of data model binding are covered in :doc:`syntax`.
 
 Changing the value of an element's attributes will change the visual appearance
 of the widget in the view. The Enaml compiler ensures that a developer does not
@@ -125,7 +125,7 @@ Model Files
 The application data models, business logic, and other support code live in
 ``.py`` files. While Enaml has the capability to interface with nearly any
 data model framework, it supports the `Atom`_ model framework out of the box.
-The full discussion of working with data models is given in the :doc:`models`
+The full discussion of working with data models is given in the :doc:`syntax`
 article. For now, the simple model given below is sufficient for the current
 example, and should be fairly self-explanatory.
 

docs/source/get_started/index.rst

@@ -12,48 +12,46 @@ When you are comfortable with the topics here, have a look at the
 
 
 .. toctree::
+    :titlesonly:
     :hidden:
 
     introduction
     installation
     anatomy
-    models
+    syntax
     layout
 
 
-:doc:`introduction`
--------------------
+.. rubric::`introduction`
 
     The introduction to Enaml explains the motivations behind the project
     and what it seeks to achieve in the context of the larger Python
     ecosystem. It presents the challenges inherent to UI development and
     how the declarative programming model is used to address them.
 
-:doc:`installation`
--------------------
+.. rubric::`installation`
 
     The installation instructions present the steps needed to install
     Enaml and its dependencies.
 
-:doc:`anatomy`
---------------
+.. rubric::`anatomy`
 
     The building blocks of an Enaml application are presented in the
     form of a runnable example. The example shows how the various
     syntactic constructs and framework components combine to create a
     simple user interface application.
 
-:doc:`models`
--------------
+.. rubric::`syntax`
 
-    One of the great features of Enaml is its ability to automatically bind
-    to data models through a rich set of operators. This section describes
-    how those operators are used to connect user defined data models to
-    Enaml views and how they automatically keep the views up-to-date when
-    the data in the models change at runtime.
+    Enaml defines a superset of Python that allows to define the UI in a 
+    declarative way. One of the great features of Enaml is its ability to 
+    automatically bind to data models through a rich set of operators. This 
+    section describes the Enaml specific part of the syntax and how those 
+    operators are used to connect user defined data models to Enaml views and 
+    how they automatically keep the views up-to-date when the data in the 
+    models change at runtime.
 
-:doc:`layout`
--------------
+.. rubric::`layout`
 
     The layout systems of typical user interface frameworks can quickly
     become tedious for all but the simplest of cases. Enaml sheds the

docs/source/get_started/installation.rst

@@ -19,8 +19,10 @@ installed and available on the system path.
 
     If installing and building Enaml and its dependencies from scratch is not
     appealing, the free (and unaffiliated) `Anaconda`_ Python distribution
-    provides a complete Python environment which comes with a reasonably
-    recent version of Enaml and a host of other useful packages.
+    provides a complete Python environment in which the last release of Enaml
+    can be installed using conda from the conda-forge channel::
+    
+    $ conda install enaml -c conda-forge
 
     If you have a working C++ compiler, you can install using pip::
 
@@ -33,7 +35,7 @@ installed and available on the system path.
 
     Enaml is known to run on Windows, OSX, and Linux; and compiles cleanly
     with MSVC, Clang, GCC, and MinGW. However, primary development of the
-    framework occurs on Windows (7 and 8), so some quirks and bugs may be
+    framework occurs on Windows (7, 8 and 10), so some quirks and bugs may be
     present on the other platforms. If you encounter a bug, please report
     it on the `Issue Tracker`_.
 
@@ -44,87 +46,114 @@ installed and available on the system path.
 ---------
 
 Enaml is a Python framework and requires a supported Python runtime. Enaml
-currently supports **Python 2.6** and **Python 2.7**. Python 3.x support may
-be added in the future, but is not currently a high priority item.
+currently supports **Python 2.7**, **Python 3.4**, **Python 3.5**,
+**Python 3.6**.
 
-The most recent Python 2.x series releases are available on the
-`Python Downloads`_ pages. Installers are available for Windows and OSX.
-Linux users should install Python using their OS package manager.
+The most recent Python releases are available on the `Python Downloads`_ pages.
+Installers are available for Windows and OSX. Linux users should install Python
+using their OS package manager.
 
 .. _Python: http://python.org
 .. _Python Downloads: http://python.org/download
 
 
-`Setuptools`_
--------------
+`Setuptools`_ and `Pip`_
+------------------------
 
 Setuptools is a Python package which makes installing other Python packages a
-breeze. Some of the installation instructions below assume that Setuptools has
-been installed in the target Python environment. Follow the relevant
-`Setuptools Install`_ instructions for adding the package to your system.
+breeze. Pip is the default package manager for Python. The installation 
+instructions below assume that Setuptools and Pip have been installed in the 
+target Python environment. Follow the relevant `Setuptools Install`_ 
+instructions for adding the package to your system.
+
+.. note::
+
+    Recent versions of Python (Python 2 >=2.7.9 or Python 3 >=3.4) installed 
+    from the official binaries install come with those tools installed.
 
 .. _Setuptools: http://pythonhosted.org/setuptools
+.. _Pip: https://pip.pypa.io/en/stable/
 .. _Setuptools Install: https://pypi.python.org/pypi/setuptools/1.1.6
+.. _Pip Install: https://pip.pypa.io/en/stable/installing/
+
+
+`Future`_
+---------
+
+Enaml supports both Python 2 and 3 and uses the future library as a 
+compatibility layer. Future can be installed with the ``pip install`` command 
+of `Pip`_::
+
+    C:\> pip install future
 
 
 `Ply`_
 ------
 
 The Enaml framework extends the grammar Python language with new declarative
-syntax constructs. To accomplish this, Enaml has a fully compliant Python 2.7
-lexer and parser with added support for the new syntax. These components are
-built using the PLY parsing tools, which contain Python implementations of lex
-and yacc.
+syntax constructs. To accomplish this, Enaml has a fully compliant Python 
+2.7/3.4/3.5/3.6 lexer and parser with added support for the new syntax. These 
+components are built using the PLY parsing tools, which contain Python 
+implementations of lex and yacc.
 
-Ply can be installed with the ``easy_install`` command of `Setuptools`_::
+Ply can be installed with the ``pip install`` command of `Pip`_::
 
-    C:\> easy_install ply
+    C:\> pip install ply
 
 .. _Ply: http://www.dabeaz.com/ply
 
 
-`PyQt4`_
---------
+`PyQt`_
+-------
 
 Enaml's declarative widgets provide a layer of abstraction on top of the
 widgets of a toolkit rendering library. While Enaml is architected to be
 toolkit agnostic, the recommended toolkit library is `Qt`_.
 
-PyQt4 is a robust set of Python bindings to the Qt toolkit.
+Enaml supports using either PyQt4 or PyQt5 and uses the `qtpy`_ library
+as compatibility layer.
+
+PyQt4 is a robust set of Python bindings to the Qt 4 toolkit.
 The `PyQt Downloads`_ page contains Windows installers which include the Qt
 binaries. OSX users can install PyQt4 via `Homebrew`_. Linux users should
 install via the system package manager.
 
-.. topic:: Note for PySide Users
+PyQt5 is a robust set of Python bindings to the Qt 5 toolkit. On Python 3,
+it can install via pip::
+
+$ pip install pyqt5
+
+.. topic:: Note for PySide/PySide2 Users
 
     Enaml has unofficial support for using the `PySide`_ bindings to Qt. To
     activate PySide support, set the environment variable ``QT_API=pyside``
-    before starting the Enaml application. Note that the PySide bindings are
-    not nearly as stable as PyQt4 and contain several bugs which can and will
-    cause applications to crash. There are also some API differences between
-    the two libraries. So while some effort is made to support the use of
-    PySide in Enaml, it is "use at your own risk".
-
-.. _PyQt4: http://www.riverbankcomputing.com/software/pyqt/intro
+    (``QT_API=pyside2`` for PySide2) before starting the Enaml application.
+    Note that the PySide bindings are not nearly as stable as PyQt and contain
+    several bugs which can and will cause applications to crash. There are also
+    some API differences between the two libraries. So while some effort is
+    made to support the use of PySide in Enaml, it is "use at your own risk".
+
+.. _PyQt: http://www.riverbankcomputing.com/software/pyqt/intro
+.. _qtpy: https://pypi.python.org/pypi/QtPy/
 .. _Qt: http://qt-project.org
 .. _PyQt Downloads: http://www.riverbankcomputing.com/software/pyqt/download
 .. _Homebrew: http://brew.sh
 .. _PySide: http://qt-project.org/wiki/PySide
 
 
-`Casuarius`_
-------------
+`Kiwisolver`_
+-------------
 
 Enaml's layout engine is built on top of the `Cassowary`_ linear constraint
 optimizer. This is the same algorithm used by the Cocoa Autolayout engine in
-OSX. Casuarius provides Python bindings to a C++ implementation of the
+OSX. Kiwisolver provides Python bindings to a C++ implementation of the
 Cassowary algorithm.
 
-The simplest way to install Casuarius is with ``easy_install``::
+The simplest way to install Kiwisolver is with ``pip``::
 
-    C:\> easy_install casuarius
+    C:\> pip install kiwisolver
 
-.. _Casuarius: https://github.com/enthought/casuarius
+.. _Kiwisolver: https://github.com/nucleic/kiwi
 .. _Cassowary: http://www.cs.washington.edu/research/constraints/cassowary