Mercurial > kallithea

annotate docs/usage/customization.rst @ 8998:a80ac2033a8a draft i18n tip

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
i18n: updated translation for Greek Currently translated at 100.0% (1082 of 1082 strings)
author Aristotelis Stageiritis <aristotelis79@gmail.com>
date Sun, 07 Apr 2024 08:07:49 +0200
parents e3d8f4bc3ce7
children
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
8655
e3d8f4bc3ce7 extensions: rename 'rcextensions' into 'extensions' but provide compatibility
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7845
diff changeset
42 Behavioral customization: Kallithea extensions
e3d8f4bc3ce7 extensions: rename 'rcextensions' into 'extensions' but provide compatibility
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7845
diff changeset
43 ----------------------------------------------
5779
60f9840c8df1 docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
44
8655
e3d8f4bc3ce7 extensions: rename 'rcextensions' into 'extensions' but provide compatibility
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7845
diff changeset
45 Some behavioral customization can be done in Python using Kallithea
e3d8f4bc3ce7 extensions: rename 'rcextensions' into 'extensions' but provide compatibility
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7845
diff changeset
46 ``extensions``, a custom Python file you can create to extend Kallithea
e3d8f4bc3ce7 extensions: rename 'rcextensions' into 'extensions' but provide compatibility
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7845
diff changeset
47 functionality.
5779
60f9840c8df1 docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
48
8655
e3d8f4bc3ce7 extensions: rename 'rcextensions' into 'extensions' but provide compatibility
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7845
diff changeset
49 With ``extensions`` it's possible to add additional mappings for Whoosh
5779
60f9840c8df1 docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
50 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
51 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
52 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
53 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
54
60f9840c8df1 docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
55 To generate a skeleton extensions package, run::
60f9840c8df1 docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
56
7415
f9c8fec48185 cli: convert 'gearbox make-rcext' in 'kallithea-cli extensions-create'
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7244
diff changeset
57 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
58
8655
e3d8f4bc3ce7 extensions: rename 'rcextensions' into 'extensions' but provide compatibility
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7845
diff changeset
59 This will create an ``extensions.py`` file next to the specified ``ini`` file.
e3d8f4bc3ce7 extensions: rename 'rcextensions' into 'extensions' but provide compatibility
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7845
diff changeset
60 You can find more details inside this file.
e3d8f4bc3ce7 extensions: rename 'rcextensions' into 'extensions' but provide compatibility
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7845
diff changeset
61
e3d8f4bc3ce7 extensions: rename 'rcextensions' into 'extensions' but provide compatibility
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7845
diff changeset
62 For compatibility with previous releases of Kallithea, a directory named
e3d8f4bc3ce7 extensions: rename 'rcextensions' into 'extensions' but provide compatibility
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7845
diff changeset
63 ``rcextensions`` with a file ``__init__.py`` inside of it can also be used. If
e3d8f4bc3ce7 extensions: rename 'rcextensions' into 'extensions' but provide compatibility
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7845
diff changeset
64 both an ``extensions.py`` file and an ``rcextensions`` directory are found, only
e3d8f4bc3ce7 extensions: rename 'rcextensions' into 'extensions' but provide compatibility
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7845
diff changeset
65 ``extensions.py`` will be loaded. Note that the name ``rcextensions`` is
e3d8f4bc3ce7 extensions: rename 'rcextensions' into 'extensions' but provide compatibility
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7845
diff changeset
66 deprecated and support for it will be removed in a future release.
5779
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
60f9840c8df1 docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
69 Behavioral customization: code changes
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
60f9840c8df1 docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
72 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
73 in the source code.
60f9840c8df1 docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
74
60f9840c8df1 docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
75 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
76 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
77 details.