Mercurial > kallithea
annotate docs/usage/customization.rst @ 7813:f79b864dc192
flake8: fix W605 invalid escape sequence
author | Mads Kiilerich <mads@kiilerich.com> |
---|---|
date | Sun, 04 Aug 2019 00:13:03 +0200 |
parents | b66725ba01ed |
children | 3b54bcf6d128 |
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. |