Update theming and development documentation

* The templates are no longer `.html` files and are dispersed throughout the source code.
* The Sass files are also no longer all in one place
* Add a section on webpack aliases for modifying templates without touching the original files

Updates #2603

docs/source/development.rst

@@ -2,7 +2,7 @@
 
     <div id="banner"><a href="https://github.com/jcbrand/converse.js/blob/master/docs/source/development.rst">Edit me on GitHub</a></div>
 
-.. _development:
+.. _`development`:
 
 ===========
 Development
@@ -25,6 +25,7 @@ to fix a bug or to add new functionality.
 
    dependencies
    style_guide
+   webserver
    plugin_development
    api/index
    testing

docs/source/index.rst

@@ -47,8 +47,8 @@ Table of Contents
    session
    configuration
    development
-   security
    theming
+   security
    translations
    troubleshooting
    documentation

docs/source/testing.rst

@@ -29,21 +29,17 @@ Automatically run tests on file changes
 ***************************************
 
 To automatically run the tests whenever you make a change to any of the
-Converse source code, you can run ``make watch`` in one terminal, and ``make
-tests`` or ``make check`` in another.
+Converse source code, you can run ``make watch`` in one terminal, and ``make tests`` in another.
 
-``make watch`` will build development bundles of Converse.js (in
-``dist/converse.js`` and ``dist/converse.css``) and automatically rebuild them
-whenever a source file is modified.
-
-Similarly, Karma will make sure that the tests are re-executed when the
-bundle files are rebuilt.
+``make watch`` will build development bundles of Converse (in ``dist/converse.js`` and ``dist/converse.css``)
+and automatically rebuild them whenever a source file is modified.
 
+Similarly, Karma will make sure that the tests are re-executed when the bundle files are rebuilt.
 
 Running individual tests
 ************************
 
-Converse has over 400 tests, and it can take a few minutes to run through all of them.
+Converse has over 400 tests, and it can take a while to run through all of them.
 
 When developing on Converse, it's often preferable to have a more rapid
 turnaround time between editing a file and checking whether the most relevant

docs/source/theming.rst

@@ -11,61 +11,61 @@ Theming
 Setting up your environment
 ===========================
 
-In order to theme Converse, you first need to set up a :ref:`development` environment.
-
-You'll also want to preview the changes you make in your browser, for which a
-webserver will be useful.
-
-To both set up the development environment and also start up a web browser to 
-serve the files for you, simply run::
-
-    make serve
-
-.. note::
-    To run the "make" commands, you'll need `GNUMake <https://www.gnu.org/software/make>`_
-    installed on your computer. If you use GNU/Linux or \*BSD, it should be installed or
-    available via your package manager. For Mac, I think you need to install XCode and in
-    Windows you can use `Chocolatey <https://chocolatey.org/>`_.
-
-After running ``make serve`` you can open http://localhost:8000 in your webbrowser you'll
-see the Converse website.
-
-However, when developing or changing the theme, you'll want to load all the
-unminified JS and CSS resources as separate files. To do this, open http://localhost:8000/dev.html
-instead.
-
+In order to theme Converse, you first need to set up a :ref:`development` environment
+and then you'll also want to follow the guide to :ref:`webserver`.
 
 Modifying the HTML templates of Converse
 ========================================
 
-The HTML markup of Converse is contained in small ``.html`` files in the
-``./src/templates`` directory.
+Converse uses `lit-html <https://lit-html.polymer-project.org/guide>`_ as HTML
+templating library, and the HTML source code is contained in JavaScript ``.js``
+files in various ``./template`` directories in the source code.
+
+Some top-level templates are found in the ``./src/templates`` directory, but
+usually the templates that are relevant to a specific plugin will be find
+inside that plugin's subdirectory.
+
+For example: `src/plugins/chatview/templates <https://github.com/conversejs/converse.js/tree/master/src/plugins/chatview/templates>`_.
 
 You can modify HTML markup that Converse generates by modifying these files.
 
-Modifying the CSS
-=================
+Use webpack aliases to modify templates without changing the original files
+---------------------------------------------------------------------------
 
-The CSS files are generated from `Sass <http://sass-lang.com>`_ files in the ``./sass`` directory.
+Generally what I do when creating a modified version of Converse for a project
+or customer, is that I create a new JavaScript package with its own
+``package.json`` and I then add ``converse.js`` as a dependency (e.g. via ``npm
+install --save converse.js``) to the ``package.json``.
 
-To generate the CSS you can run::
+Then I add a Webpack configuration and use `webpack aliases <https://webpack.js.org/configuration/resolve/#resolvealias>`_
+to resolve template paths to my own modified files.
 
-    make css
+For example, in the webpack configuration snippet below, I add two aliases, so
+that the ``message-body.js`` and ``message.js`` templates can be replaced with
+two of my own custom templates.
 
-Testing your changes
-====================
+.. code-block:: javascript
 
-The recommended way to test your changes is to run the tests that are part of the Converse source code.
-By executing ``make test`` you'll run all tests (which live in the ``spec`` folder) which will open a browser window in which tests are processed.
+    resolve: {
+        extensions: ['.js'],
+        alias: {
+        './message-body.js': path.resolve(__dirname, 'path/to/my/custom/message-body.js'),
+        './templates/message.js': path.resolve(__dirname, 'path/to/my/custom/chat_message.js'),
+        }
+    }
 
-You can run a single test by changing ``it(`` to ``fit(`` so that only that one test runs. Then you click the "debug" button in the browser when the tests run. After the test has run, the opened chats will still be visible.
+Modifying the CSS
+=================
 
+The CSS files are generated from `Sass <http://sass-lang.com>`_ files that end in ``.scss`` and
+which are distributed throughout the source code.
 
-Creating dist files
-===================
+Similarly to the template files, the CSS that is relevant to a particular plugin
+is usually inside the ``./styles`` directory inside the relevant plugin
+directory.
 
-Once you've themed Converse, you'll want to create new minified distribution
-files of all the JavaScript and CSS.
+For example: `src/plugins/controlbox/styles <https://github.com/conversejs/converse.js/tree/master/src/plugins/controlbox/styles>`_.
 
-Please refer to the :doc:`builds` section for information on how this is done.
+To generate the CSS you can run::
 
+    make css

docs/source/webserver.rst

@@ -0,0 +1,51 @@
+.. raw:: html
+
+    <div id="banner"><a href="https://github.com/jcbrand/converse.js/blob/master/docs/source/webserver.rst">Edit me on GitHub</a></div>
+
+
+.. _`webserver`:
+
+Setting up a webserver
+======================
+
+When making changes to Converse, either development or theming changes,
+you'll want to preview them in your browser.
+
+For this, you'll need to serve the development files via a web server,
+so that you can see your local changes in the browser.
+
+Manually starting a web server
+------------------------------
+
+To both set up the development environment and also start up a web browser to
+serve the files for you, you can run::
+
+    make serve
+
+.. note::
+    To run the "make" commands, you'll need `GNUMake <https://www.gnu.org/software/make>`_
+    installed on your computer. If you use GNU/Linux or \*BSD, it should be installed or
+    available via your package manager. For Mac, you'll need to install XCode and in
+    Windows you can use `Chocolatey <https://chocolatey.org/>`_.
+
+After running ``make serve`` you can open http://localhost:8000 in your webbrowser to see the Converse website.
+
+When developing or changing the theme, you'll want to load all the
+unminified JS and CSS resources as separate files. To do this, open http://localhost:8000/dev.html instead.
+
+You might want to open `dev.html <https://github.com/conversejs/converse.js/blob/master/dev.html>`_ in your text editor or IDE as well, to see
+how ``converse.initialize`` is called and to potentially change any of the
+settings.
+
+If you're running ``make devserver``, you need to open http://localhost:8080
+instead.
+
+Starting a web server with live reloading
+-----------------------------------------
+
+Alternatively, if you want to have live reloading whenever any of the source files change, you
+can run ``make devserver`` (which will use `webpack-dev-server <https://github.com/webpack/webpack-dev-server>`_).
+
+Instead of ``dev.html`` being used, `webpack.html <https://github.com/conversejs/converse.js/blob/master/webpack.html>`_
+is now being used as the HTML template, and you'll need to modify that file if
+you want to change the settings passed to ``converse.initialize``.