Mercurial > kallithea
annotate docs/usage/customization.rst @ 7415:f9c8fec48185
cli: convert 'gearbox make-rcext' in 'kallithea-cli extensions-create'
Note: 'extensions' instead of 'rcextensions' as first step to get away from
the 'rc' prefix.
author | Thomas De Schampheleire <thomas.de_schampheleire@nokia.com> |
---|---|
date | Sun, 18 Nov 2018 20:02:17 +0100 |
parents | 8152f9e6a778 |
children | b66725ba01ed |
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 |
8152f9e6a778
less: load optional theme.less file to allow custom styles
domruf <dominikruf@gmail.com>
parents:
6554
diff
changeset
|
31 After creating the ``theme.less`` file, you need to regenerate the CSS files. |
8152f9e6a778
less: load optional theme.less file to allow custom styles
domruf <dominikruf@gmail.com>
parents:
6554
diff
changeset
|
32 Install npm for your platform and run:: |
8152f9e6a778
less: load optional theme.less file to allow custom styles
domruf <dominikruf@gmail.com>
parents:
6554
diff
changeset
|
33 |
8152f9e6a778
less: load optional theme.less file to allow custom styles
domruf <dominikruf@gmail.com>
parents:
6554
diff
changeset
|
34 npm install |
8152f9e6a778
less: load optional theme.less file to allow custom styles
domruf <dominikruf@gmail.com>
parents:
6554
diff
changeset
|
35 npm run less |
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 in the Kallithea root directory. |
8152f9e6a778
less: load optional theme.less file to allow custom styles
domruf <dominikruf@gmail.com>
parents:
6554
diff
changeset
|
38 |
8152f9e6a778
less: load optional theme.less file to allow custom styles
domruf <dominikruf@gmail.com>
parents:
6554
diff
changeset
|
39 .. _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
|
40 .. _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
|
41 .. _less: http://lesscss.org/ |
8152f9e6a778
less: load optional theme.less file to allow custom styles
domruf <dominikruf@gmail.com>
parents:
6554
diff
changeset
|
42 |
8152f9e6a778
less: load optional theme.less file to allow custom styles
domruf <dominikruf@gmail.com>
parents:
6554
diff
changeset
|
43 |
5779
60f9840c8df1
docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff
changeset
|
44 Behavioral customization: rcextensions |
60f9840c8df1
docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff
changeset
|
45 -------------------------------------- |
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 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
|
48 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
|
49 |
60f9840c8df1
docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff
changeset
|
50 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
|
51 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
|
52 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
|
53 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
|
54 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
|
55 |
60f9840c8df1
docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff
changeset
|
56 To generate a skeleton extensions package, run:: |
60f9840c8df1
docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff
changeset
|
57 |
7415
f9c8fec48185
cli: convert 'gearbox make-rcext' in 'kallithea-cli extensions-create'
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents:
7244
diff
changeset
|
58 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
|
59 |
60f9840c8df1
docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff
changeset
|
60 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
|
61 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
|
62 for more details. |
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 Behavioral customization: code changes |
60f9840c8df1
docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff
changeset
|
66 -------------------------------------- |
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 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
|
69 in the source code. |
60f9840c8df1
docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff
changeset
|
70 |
60f9840c8df1
docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff
changeset
|
71 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
|
72 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
|
73 details. |