Mercurial > kallithea

annotate docs/usage/customization.rst @ 7445:a33d1337db05

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
tests: remove tests of UI notifications This commit is part of the removal of the UI notification feature from Kallithea, which is not deemed useful in its current form. Only email notifications are preserved.
author Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
date Wed, 05 Dec 2018 07:40:00 +0100
parents b66725ba01ed
children 3b54bcf6d128
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
5779
60f9840c8df1 docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
1 .. _customization:
60f9840c8df1 docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
2
60f9840c8df1 docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
3 =============
60f9840c8df1 docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
4 Customization
60f9840c8df1 docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
5 =============
60f9840c8df1 docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
6
60f9840c8df1 docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
7 There are several ways to customize Kallithea to your needs depending on what
60f9840c8df1 docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
8 you want to achieve.
60f9840c8df1 docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
9
60f9840c8df1 docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
10
60f9840c8df1 docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
11 HTML/JavaScript/CSS customization
60f9840c8df1 docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
12 ---------------------------------
60f9840c8df1 docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
13
60f9840c8df1 docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
14 To customize the look-and-feel of the web interface (for example to add a
60f9840c8df1 docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
15 company banner or some JavaScript widget or to tweak the CSS style definitions)
60f9840c8df1 docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
16 you can enter HTML code (possibly with JavaScript and/or CSS) directly via the
60f9840c8df1 docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
17 *Admin > Settings > Global > HTML/JavaScript customization
60f9840c8df1 docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
18 block*.
60f9840c8df1 docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
19
60f9840c8df1 docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
20
7244
8152f9e6a778 less: load optional theme.less file to allow custom styles
domruf <dominikruf@gmail.com>
parents: 6554
diff changeset
21 Style sheet customization with Less
8152f9e6a778 less: load optional theme.less file to allow custom styles
domruf <dominikruf@gmail.com>
parents: 6554
diff changeset
22 -----------------------------------
8152f9e6a778 less: load optional theme.less file to allow custom styles
domruf <dominikruf@gmail.com>
parents: 6554
diff changeset
23
8152f9e6a778 less: load optional theme.less file to allow custom styles
domruf <dominikruf@gmail.com>
parents: 6554
diff changeset
24 Kallithea uses `Bootstrap 3`_ and Less_ for its style definitions. If you want
8152f9e6a778 less: load optional theme.less file to allow custom styles
domruf <dominikruf@gmail.com>
parents: 6554
diff changeset
25 to make some customizations, we recommend to do so by creating a ``theme.less``
8152f9e6a778 less: load optional theme.less file to allow custom styles
domruf <dominikruf@gmail.com>
parents: 6554
diff changeset
26 file. When you create a file named ``theme.less`` in the Kallithea root
8152f9e6a778 less: load optional theme.less file to allow custom styles
domruf <dominikruf@gmail.com>
parents: 6554
diff changeset
27 directory, you can use this file to override the default style. For example,
8152f9e6a778 less: load optional theme.less file to allow custom styles
domruf <dominikruf@gmail.com>
parents: 6554
diff changeset
28 you can use this to override ``@kallithea-theme-main-color``,
8152f9e6a778 less: load optional theme.less file to allow custom styles
domruf <dominikruf@gmail.com>
parents: 6554
diff changeset
29 ``@kallithea-logo-url`` or other `Bootstrap variables`_.
8152f9e6a778 less: load optional theme.less file to allow custom styles
domruf <dominikruf@gmail.com>
parents: 6554
diff changeset
30
7437
b66725ba01ed cli: add command 'kallithea-cli front-end-build'
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7415
diff changeset
31 After creating the ``theme.less`` file, you need to regenerate the CSS files, by
b66725ba01ed cli: add command 'kallithea-cli front-end-build'
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7415
diff changeset
32 running::
7244
8152f9e6a778 less: load optional theme.less file to allow custom styles
domruf <dominikruf@gmail.com>
parents: 6554
diff changeset
33
7437
b66725ba01ed cli: add command 'kallithea-cli front-end-build'
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7415
diff changeset
34 kallithea-cli front-end-build --no-install-deps
7244
8152f9e6a778 less: load optional theme.less file to allow custom styles
domruf <dominikruf@gmail.com>
parents: 6554
diff changeset
35
8152f9e6a778 less: load optional theme.less file to allow custom styles
domruf <dominikruf@gmail.com>
parents: 6554
diff changeset
36 .. _bootstrap 3: https://getbootstrap.com/docs/3.3/
8152f9e6a778 less: load optional theme.less file to allow custom styles
domruf <dominikruf@gmail.com>
parents: 6554
diff changeset
37 .. _bootstrap variables: https://getbootstrap.com/docs/3.3/customize/#less-variables
8152f9e6a778 less: load optional theme.less file to allow custom styles
domruf <dominikruf@gmail.com>
parents: 6554
diff changeset
38 .. _less: http://lesscss.org/
8152f9e6a778 less: load optional theme.less file to allow custom styles
domruf <dominikruf@gmail.com>
parents: 6554
diff changeset
39
8152f9e6a778 less: load optional theme.less file to allow custom styles
domruf <dominikruf@gmail.com>
parents: 6554
diff changeset
40
5779
60f9840c8df1 docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
41 Behavioral customization: rcextensions
60f9840c8df1 docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
42 --------------------------------------
60f9840c8df1 docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
43
60f9840c8df1 docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
44 Some behavioral customization can be done in Python using ``rcextensions``, a
60f9840c8df1 docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
45 custom Python package that can extend Kallithea functionality.
60f9840c8df1 docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
46
60f9840c8df1 docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
47 With ``rcextensions`` it's possible to add additional mappings for Whoosh
60f9840c8df1 docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
48 indexing and statistics, to add additional code into the push/pull/create/delete
60f9840c8df1 docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
49 repository hooks (for example to send signals to build bots such as Jenkins) and
60f9840c8df1 docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
50 even to monkey-patch certain parts of the Kallithea source code (for example
60f9840c8df1 docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
51 overwrite an entire function, change a global variable, ...).
60f9840c8df1 docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
52
60f9840c8df1 docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
53 To generate a skeleton extensions package, run::
60f9840c8df1 docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
54
7415
f9c8fec48185 cli: convert 'gearbox make-rcext' in 'kallithea-cli extensions-create'
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7244
diff changeset
55 kallithea-cli extensions-create -c my.ini
5779
60f9840c8df1 docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
56
60f9840c8df1 docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
57 This will create an ``rcextensions`` package next to the specified ``ini`` file.
60f9840c8df1 docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
58 See the ``__init__.py`` file inside the generated ``rcextensions`` package
60f9840c8df1 docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
59 for more details.
60f9840c8df1 docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
60
60f9840c8df1 docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
61
60f9840c8df1 docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
62 Behavioral customization: code changes
60f9840c8df1 docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
63 --------------------------------------
60f9840c8df1 docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
64
60f9840c8df1 docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
65 As Kallithea is open-source software, you can make any changes you like directly
60f9840c8df1 docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
66 in the source code.
60f9840c8df1 docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
67
60f9840c8df1 docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
68 We encourage you to send generic improvements back to the
60f9840c8df1 docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
69 community so that Kallithea can become better. See :ref:`contributing` for more
60f9840c8df1 docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
70 details.