Add theming documentation and extend the docs on creating builds.

This commit is contained in:
JC Brand 2015-02-05 15:58:51 +01:00
parent d20a8a65e4
commit ec51c3660a
4 changed files with 116 additions and 27 deletions

View File

@ -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.
.. 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
This command does the following:
* 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>`_.
* 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.
* 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.
* 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`:
Minification
============
Minifying the CSS
-----------------
Minifying Javascript and CSS
----------------------------
To only minify the CSS files, nothing else, run the following command::
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``).
make cssmin
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.
The CSS files are minified via `cssmin <https://github.com/gruntjs/grunt-contrib-cssmin>`_.
To minify the Javascript and CSS, run the following command:
::
grunt minify
Javascript 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>`_.
CSS is minified via `cssmin <https://github.com/gruntjs/grunt-contrib-cssmin>`_.

View File

@ -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)
=====================================

View File

@ -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

63
docs/source/theming.rst Normal file
View File

@ -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.