# HG changeset patch
# User Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
# Date 2016-03-14 22:13:19
# Node ID 60f9840c8df1da94656f0d10c2a291100370e614
# Parent  64e2d5a291a7bb8d13fbe72f5a30ca0ec4d96090

docs: document Kallithea customization options

Create basic documentation for the various customization options in
Kallithea. Move the rcextensions section to this new page and reword.

diff --git a/docs/index.rst b/docs/index.rst
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -44,6 +44,7 @@ Kallithea Documentation
    usage/backup
    usage/debugging
    usage/troubleshooting
+   usage/customization
 
 **Development**
 
diff --git a/docs/setup.rst b/docs/setup.rst
--- a/docs/setup.rst
+++ b/docs/setup.rst
@@ -67,24 +67,6 @@ You are now ready to use Kallithea. To r
   repositories.
 
 
-Extensions
-----------
-
-Optionally one can create an ``rcextensions`` package that extends Kallithea
-functionality.
-To generate a skeleton extensions package, run::
-
-    paster make-rcext my.ini
-
-This will create an ``rcextensions`` package next to the specified ``ini`` file.
-With ``rcextensions`` it's possible to add additional mapping for whoosh,
-stats and add additional code into the push/pull/create/delete repo hooks,
-for example for sending signals to build-bots such as Jenkins.
-
-See the ``__init__.py`` file inside the generated ``rcextensions`` package
-for more details.
-
-
 Using Kallithea with SSH
 ------------------------
 
diff --git a/docs/usage/customization.rst b/docs/usage/customization.rst
new file mode 100644
--- /dev/null
+++ b/docs/usage/customization.rst
@@ -0,0 +1,50 @@
+.. _customization:
+
+=============
+Customization
+=============
+
+There are several ways to customize Kallithea to your needs depending on what
+you want to achieve.
+
+
+HTML/JavaScript/CSS customization
+---------------------------------
+
+To customize the look-and-feel of the web interface (for example to add a
+company banner or some JavaScript widget or to tweak the CSS style definitions)
+you can enter HTML code (possibly with JavaScript and/or CSS) directly via the
+*Admin > Settings > Global > HTML/JavaScript customization
+block*.
+
+
+Behavioral customization: rcextensions
+--------------------------------------
+
+Some behavioral customization can be done in Python using ``rcextensions``, a
+custom Python package that can extend Kallithea functionality.
+
+With ``rcextensions`` it's possible to add additional mappings for Whoosh
+indexing and statistics, to add additional code into the push/pull/create/delete
+repository hooks (for example to send signals to build bots such as Jenkins) and
+even to monkey-patch certain parts of the Kallithea source code (for example
+overwrite an entire function, change a global variable, ...).
+
+To generate a skeleton extensions package, run::
+
+    paster make-rcext my.ini
+
+This will create an ``rcextensions`` package next to the specified ``ini`` file.
+See the ``__init__.py`` file inside the generated ``rcextensions`` package
+for more details.
+
+
+Behavioral customization: code changes
+--------------------------------------
+
+As Kallithea is open-source software, you can make any changes you like directly
+in the source code.
+
+We encourage you to send generic improvements back to the
+community so that Kallithea can become better. See :ref:`contributing` for more
+details.