Mercurial > kallithea

annotate docs/usage/customization.rst @ 7356:39bdf0ab2862

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
hooks: use os.environ directly for KALLITHEA_EXTRAS instead of sometimes passing it as parameter It is better to be consistent ... even if that means always using the global environment that is hard to avoid.
author Mads Kiilerich <mads@kiilerich.com>
date Wed, 08 Aug 2018 02:23:11 +0200
parents 8152f9e6a778
children f9c8fec48185
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
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
6554
2c3d30095d5e gearbox: replace paster with something TurboGears2-ish that still works with the Pylons stack
Mads Kiilerich <madski@unity3d.com>
parents: 5779
diff changeset
58 gearbox make-rcext -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.