Add theming documentation and extend the docs on creating builds.

docs/source/builds.rst

@@ -1,6 +1,8 @@
-======================
-Creating custom builds
-======================
+.. _builds:
+
+===============
+Creating builds
+===============
 
 .. contents:: Table of Contents
    :depth: 3
@@ -10,31 +12,53 @@ Creating custom builds
 .. warning:: There current documentation in this section does not adequately
     explain how to create custom builds.
 
-.. _`minification`:
+.. note:: Please make sure to read the section :doc:`development` and that you have installed
+    all development dependencies (long story short, you should be able to just run  ``make dev``)
+
+Creating builds
+===============
+
+We  use `require.js <http://requirejs.org>`_ to keep track of *Converse.js* and
+its dependencies and to to bundle them together in a single file fit for
+deployment to a production site.
+
+To create the bundles, simply run::
+
+    make build
 
-Minification
-============
+This command does the following:
 
-Minifying Javascript and CSS
-----------------------------
+* It creates different Javascript bundles of Converse.js.
+  The individual javascript files will be bundled and minified with `require.js`_'s
+  optimization tool, using `almond <https://github.com/jrburke/almond>`_.
+  You can `read more about require.js's optimizer here <http://requirejs.org/docs/optimization.html>`_.
 
-Please make sure to read the section :doc:`development` and that you have installed
-all development dependencies (long story short, you can run ``npm install``
-and then ``grunt fetch``).
+* It bundles the HTML templates in ``./src/templates/`` into a single file called ``templates.js``.
+  This file can then be included via the ``<script>`` tag. See for example the ``non_amd.html`` example page.
 
-We  use `require.js <http://requirejs.org>`_ to keep track of *Converse.js* and its dependencies and to
-to bundle them together in a single minified file fit for deployment to a
-production site.
+* It bundles all the translation files in ``./locale/`` into a single file ``locales.js``.
+  This file can then be included via the ``<script>`` tag. See for example the ``non_amd.html`` example page.
 
-To minify the Javascript and CSS, run the following command:
+* Also, the CSS files in the ``./css`` directory will be minified.
+
+The built Javasript bundles are contained in the ``./builds`` directory:
+
+.. code-block:: bash
+
+    jc@conversejs:~/converse.js (master)$ ls builds/
+    converse.js               converse-no-locales-no-otr.js      converse.website.min.js
+    converse.min.js           converse-no-locales-no-otr.min.js  converse.website-no-otr.min.js
+    converse.nojquery.js      converse-no-otr.js                 locales.js
+    converse.nojquery.min.js  converse-no-otr.min.js             templates.js
+
+.. _`minification`:
 
-::
+Minifying the CSS
+-----------------
 
-    grunt minify
+To only minify the CSS files, nothing else, run the following command::
 
-Javascript will be bundled and minified with `require.js`_'s optimization tool,
-using `almond <https://github.com/jrburke/almond>`_.
+    make cssmin
 
-You can `read more about require.js's optimizer here <http://requirejs.org/docs/optimization.html>`_.
+The CSS files  are minified via `cssmin <https://github.com/gruntjs/grunt-contrib-cssmin>`_.
 
-CSS is minified via `cssmin <https://github.com/gruntjs/grunt-contrib-cssmin>`_.

docs/source/development.rst

@@ -1,3 +1,5 @@
+.. _development:
+
 ===========
 Development
 ===========
@@ -74,7 +76,6 @@ If you are curious to know what the different dependencies are:
     Double-check the output of ```make dev``` to see if there are any errors
     listed. For support, you can write to the mailing list: conversejs@librelist.com
 
-
 With AMD and require.js (recommended)
 =====================================
 

docs/source/index.rst

@@ -33,7 +33,7 @@ The :ref:`what-you-will-need` and :ref:`session-support` sections provide more i
 
 Table of Contents
 =================
- 
+
 .. toctree::
    :maxdepth: 2
 
@@ -42,6 +42,7 @@ Table of Contents
    setup
    configuration
    development
+   theming
    translations
    documentation
    builds

docs/source/theming.rst

@@ -0,0 +1,63 @@
+=======
+Theming
+=======
+
+.. contents:: Table of Contents
+   :depth: 2
+   :local:
+
+Setting up your environment
+===========================
+
+In order to theme converse.js, you'll first need to set up a `development_` environment.
+
+You'll also want to preview the changes you make in the browser.
+
+To set up the development environment and also start up a web browser which
+will serve the files for you, simply run::
+
+    make serve
+
+You can now open http://localhost:8000 in your webbrowser to see the
+converse.js website.
+
+However, when developing or changing the theme, you'll want to load all the
+unminified JS and CSS resources. To do this, open http://localhost:8000/dev.html
+instead.
+
+Mockups
+=======
+
+Converse.js contains some mockups in the ``./mockup`` directory against which you
+can preview and tweak your changes.
+
+The ``./mockup/index.html`` file contains the most comprehensive mockup, while
+the other files focus on particular UI aspects.
+
+To see it in your browser, simply open: http://localhost:8000/mockup
+
+
+Modifying the HTML templates of Converse.js
+===========================================
+
+The HTML markup of converse.js is contained small ``.html`` files in the
+``./src/templates`` directory.
+
+Modifying the CSS
+=================
+
+The CSS files are generated from `Sass <http://sass-lang.com>`_ files in
+the ``./sass`` directory.
+
+To generate the CSS you can run::
+
+    make css
+
+Creating builds
+===============
+
+Once you've themed converse.js, you'll want to create new minified builds of
+the Javascript and CSS files.
+
+Please refer to the :doc:`builds` section for information on how this is done.
+