Mercurial > kallithea

annotate docs/usage/customization.rst @ 8395:482e163caccd i18n

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Merge closed stable-i18n Everything has already landed.
author Mads Kiilerich <mads@kiilerich.com>
date Mon, 04 May 2020 19:24:04 +0200
parents 3b54bcf6d128
children e3d8f4bc3ce7
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``
7845
3b54bcf6d128 front-end: fix documentation regarding theme.less file
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7437
diff changeset
26 file. When you create a file named ``theme.less`` in directory
3b54bcf6d128 front-end: fix documentation regarding theme.less file
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7437
diff changeset
27 ``kallithea/front-end/`` inside the Kallithea installation, you can use this
3b54bcf6d128 front-end: fix documentation regarding theme.less file
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7437
diff changeset
28 file to override the default style. For example, you can use this to override
3b54bcf6d128 front-end: fix documentation regarding theme.less file
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7437
diff changeset
29 ``@kallithea-theme-main-color``, ``@kallithea-logo-url`` or other `Bootstrap
3b54bcf6d128 front-end: fix documentation regarding theme.less file
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7437
diff changeset
30 variables`_.
7244
8152f9e6a778 less: load optional theme.less file to allow custom styles
domruf <dominikruf@gmail.com>
parents: 6554
diff changeset
31
7437
b66725ba01ed cli: add command 'kallithea-cli front-end-build'
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7415
diff changeset
32 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
33 running::
7244
8152f9e6a778 less: load optional theme.less file to allow custom styles
domruf <dominikruf@gmail.com>
parents: 6554
diff changeset
34
7437
b66725ba01ed cli: add command 'kallithea-cli front-end-build'
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7415
diff changeset
35 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
36
8152f9e6a778 less: load optional theme.less file to allow custom styles
domruf <dominikruf@gmail.com>
parents: 6554
diff changeset
37 .. _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
38 .. _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
39 .. _less: http://lesscss.org/
8152f9e6a778 less: load optional theme.less file to allow custom styles
domruf <dominikruf@gmail.com>
parents: 6554
diff changeset
40
8152f9e6a778 less: load optional theme.less file to allow custom styles
domruf <dominikruf@gmail.com>
parents: 6554
diff changeset
41
5779
60f9840c8df1 docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
42 Behavioral customization: rcextensions
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
60f9840c8df1 docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
45 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
46 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
47
60f9840c8df1 docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
48 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
49 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
50 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
51 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
52 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
53
60f9840c8df1 docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
54 To generate a skeleton extensions package, run::
60f9840c8df1 docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
55
7415
f9c8fec48185 cli: convert 'gearbox make-rcext' in 'kallithea-cli extensions-create'
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7244
diff changeset
56 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
57
60f9840c8df1 docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
58 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
59 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
60 for more details.
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
60f9840c8df1 docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
63 Behavioral customization: code changes
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
60f9840c8df1 docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
66 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
67 in the source code.
60f9840c8df1 docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
68
60f9840c8df1 docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
69 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
70 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
71 details.