Update development docs and add theming info

docs/source/configuration.rst

@@ -760,6 +760,8 @@ loglevel
 
 You can also set this value by changing a URL fragment `#converse?loglevel=debug`
 
+.. _`dark_theme`:
+
 dark_theme
 ----------
 
@@ -2163,6 +2165,8 @@ If set to ``false``, this feature is disabled.
 
 If set to ``a resource name``, Converse will synchronize only with a client that has that particular resource assigned to it.
 
+.. _`theme`:
+
 theme
 -----
 

docs/source/dependencies.rst

@@ -2,9 +2,11 @@
 
     <div id="banner"><a href="https://github.com/jcbrand/converse.js/blob/master/docs/source/theming.rst">Edit me on GitHub</a></div>
 
-=============================
-Starting up a dev environment
-=============================
+.. _`development`:
+
+============================
+Setting up a dev environment
+============================
 
 Installing the 3rd party dependencies
 =====================================
@@ -88,3 +90,50 @@ which requires all other dependent JavaScript code to also be open sourced under
 license. You might not be willing to adhere to those terms, which is why you
 need to decide for yourself whether you're going to load libsignal or not.
 
+
+.. _`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.
+
+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``.
+
+If you're running ``make devserver``, you need to open http://localhost:8080.
+

docs/source/development.rst

@@ -23,11 +23,10 @@ to fix a bug or to add new functionality.
 .. toctree::
    :maxdepth: 2
 
-   dependencies
-   style_guide
-   webserver
+   setup_dev_environment 
    plugin_development
    api/index
    testing
    other_frameworks
    builds
+   style_guide

docs/source/setup_dev_environment.rst

@@ -0,0 +1,140 @@
+.. raw:: html
+
+    <div id="banner"><a href="https://github.com/jcbrand/converse.js/blob/master/docs/source/theming.rst">Edit me on GitHub</a></div>
+
+.. _`setup_dev_environment`:
+
+============================
+Setting up a dev environment
+============================
+
+Installing the 3rd party dependencies
+=====================================
+
+To develop and customize Converse, you'll first need to check out Converse's Git
+repository:
+
+::
+
+    git clone https://github.com/conversejs/converse.js.git
+    cd converse.js
+
+
+We use development tools which depend on Node.js and NPM (the Node package manager).
+
+It's recommended that you use `NVM <https://github.com/nvm-sh/nvm>`_ (the Node version manager)
+to make sure you have the right version of Node.
+
+Refer to the `NVM Github page <https://github.com/nvm-sh/nvm#install--update-script>`_ for instructions on how to install it.
+
+Once NVM is installed, you can run the following inside your checkout of the Converse Git repository:
+
+::
+
+    nvm install
+
+.. note::
+    You will always have to first run ``nvm install`` in a new terminal session in order to use the
+    recommended version of Node before working on Converse.
+
+
+To set up the Converse development environment, you now run ``make dev``.
+
+::
+
+    make dev
+
+Alternatively, if you're using Windows, or don't have GNU Make installed, you can run the
+following:
+
+::
+
+  npm install
+  npm run lerna
+
+This will install the Node development tools and Converse's dependencies.
+
+The front-end dependencies are those JavaScript files on which
+Converse directly depends and which will be loaded in the browser as part of
+the bundle in ``dist/converse.js`` (or ``dist/converse.min.js``).
+
+To see the 3rd party dependencies (not just the front-end dependencies, but
+also ones necessary for development tasks like making builds), take a look at
+the list under the ``devDependencies`` in `package.json <https://github.com/jcbrand/converse.js/blob/master/package.json>`_.
+
+.. note::
+    After running ```make dev```, you should now have a new *node_modules* directory
+    which contains all the external dependencies of Converse.
+    If this directory does NOT exist, something must have gone wrong.
+    Double-check the output of ```make dev``` to see if there are any errors
+    listed. For support, you can ask in our chatroom: `dicuss@conference.conversejs.org <xmpp:discuss@conference.conversejs.org>`_.
+
+    If you don't have an XMPP client installed, follow this link to
+    `conversejs.org <https://conversejs.org/fullscreen#converse/room?jid=discuss@conference.conversejs.org>`_
+    where you can log in and be taken directly to the chatroom.
+
+
+.. _`dependency-libsignal`:
+
+Libsignal
+---------
+
+If you want OMEMO encryption, you need to load `libsignal <https://github.com/signalapp/libsignal-protocol-javascript>`_ separately in your page.
+
+For example::
+
+    <script src="3rdparty/libsignal-protocol-javascript/dist/libsignal-protocol.js"></script>
+
+The reason libsignal needs to be loaded separately is because it's released
+under the `GPLv3 <https://github.com/signalapp/libsignal-protocol-javascript/blob/master/LICENSE>`_
+which requires all other dependent JavaScript code to also be open sourced under the same
+license. You might not be willing to adhere to those terms, which is why you
+need to decide for yourself whether you're going to load libsignal or not.
+
+
+.. _`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.
+
+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``.
+
+If you're running ``make devserver``, you need to open http://localhost:8080.
+

docs/source/theming.rst

@@ -11,19 +11,109 @@ Theming
 Setting up your environment
 ===========================
 
-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`.
+In order to theme Converse, you first need to follow the steps for :ref:`setup_dev_environment`, including :ref:`webserver`.
+
+Creating a custom theme
+=======================
+
+Converse can be themed via CSS custom properties (aka CSS variables) and it has
+some themes available in its source repository.
+
+A theme is a CSS file with a specific rule that defines the theme's CSS properties.
+The rule has a specific selector that must include (and determines) the theme name.
+
+Inside this CSS rule, various CSS variables are assigned values.
+The CSS variables mainly refer to the colors that comprise the theme.
+If you don't specify a value for a specific CSS variable, then the value from
+the ``classic`` theme is used, as defined in `classic.scss <https://github.com/conversejs/converse.js/tree/master/src/shared/styles/themes/classic.scss>`_.
+
+The native theme files can be found in `shared/styles/themes <https://github.com/conversejs/converse.js/tree/master/src/shared/styles/themes>`_.
+
+Note, the Converse theme files have a ``.scss`` extension because they are compiled
+by the Sass compiler into normal CSS files. It's however not necessary to use
+Sass, basic CSS files will also suffice.
+
+The theme that Converse uses can be set via the :ref:`theme` configuration
+setting (and the :ref:`dark_theme` configuration setting for dark mode).
+
+How are themes applied?
+-----------------------
+
+When you set a value for the :ref:`theme` configuration setting, Converse will add
+a class ``theme-${api.settings.get('theme')}`` on the ``converse-root`` DOM
+element.
+
+So, for example, if you set the ``theme`` setting to ``"dracula"``, then the
+``converse-root`` element will get the class ``theme-dracula``.
+
+.. code-block:: javascript
+
+    converse.initialize({ theme: "dracula" });
+
+
+.. code-block:: html
+
+    <converse-root class="conversejs theme-dracula"></converse-root>
+
+
+The apply a theme, there then needs to be a CSS rule with a selector that matches the
+``theme-dracula`` class on the ``converse-root`` element.
+
+If you take a look at the theme file `dracula.scss <https://github.com/conversejs/converse.js/tree/master/src/shared/styles/themes/dracula.scss>`_
+you'll see that it defines a CSS rule with the selector
+``.conversejs.theme-dracula``.
+
+This selector matches any DOM element with both the classes ``.conversejs`` and
+``.theme-dracula``. The ``converse-root`` element will already have the class
+``.conversejs`` and it will have the class ``.theme-dracula`` if the ``theme``
+(or ``dark_theme`` in dark mode) configuration setting is set to ``"dracula"``.
+
+This is how themes are applied, by defining a CSS selector that matches the
+class ``.theme-${name}`` (where ``name`` is a variable containing the name of
+the theme), and then setting the ``theme`` (and/or ``dark_theme``) configuration
+setting.
+
+To create your own theme, you can create a similar CSS rule that matches
+your theme's name and then you set the ``theme`` configuration setting to that
+name. This CSS rule can be in any CSS file that is loaded in your website, or
+you can even put it in the DOM as an inline style.
+
+Modifying the CSS
+=================
+
+To create a new theme with different colors, it should be enough to create a
+theme file that sets the various CSS variables (as described above).
+
+For other CSS-related changes, you can make a specific
+CSS rule with that matches the element you want to change.
+
+Sometimes it might however be neccessary to modify the core CSS files from
+Converse, for example if you're developing new features or fixing styling bugs.
+
+The CSS files are generated from `Sass <http://sass-lang.com>`_ files that end in ``.scss`` and
+which are distributed throughout the source code.
+
+The CSS that is relevant to a particular plugin
+is usually inside the ``./styles`` directory inside the relevant plugin directory.
+
+For example: `src/plugins/controlbox/styles <https://github.com/conversejs/converse.js/tree/master/src/plugins/controlbox/styles>`_.
+
+If you're running ``make watch``, then the CSS will automatically be
+regenerated when you've changed any of the ``.scss``.
+
+You can also manually generate the CSS::
+
+    make css
 
 Modifying the HTML templates of Converse
 ========================================
 
-Converse uses `lit-html <https://lit-html.polymer-project.org/guide>`_ as HTML
+Converse uses `lit-html <https://lit.dev/docs/libraries/standalone-templates/>`_ 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.
+Some top-level templates are also in the ``./src/templates`` directory, but
+the templates that are relevant to a specific plugin should be inside that plugin's subdirectory.
 
 For example: `src/plugins/chatview/templates <https://github.com/conversejs/converse.js/tree/master/src/plugins/chatview/templates>`_.
 
@@ -53,19 +143,3 @@ two of my own custom templates.
         './templates/message.js': path.resolve(__dirname, 'path/to/my/custom/chat_message.js'),
         }
     }
-
-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.
-
-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.
-
-For example: `src/plugins/controlbox/styles <https://github.com/conversejs/converse.js/tree/master/src/plugins/controlbox/styles>`_.
-
-To generate the CSS you can run::
-
-    make css

docs/source/webserver.rst

@@ -1,51 +0,0 @@
-.. 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.
-
-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``.
-
-If you're running ``make devserver``, you need to open http://localhost:8080.
-