annotate docs/usage/customization.rst @ 6554:2c3d30095d5e

gearbox: replace paster with something TurboGears2-ish that still works with the Pylons stack This is a step towards moving away from the Pylons stack to TurboGears2, but still independent of it. Some notes from the porting - it could perhaps be the missing(?) documentation for migrating from paster to gearbox: Note: 'gearbox' without parameters will crash - specify '-h' to get started testing. Replace paster summary = 'yada yada' with the first line of the docstring of the Command class ... or override get_description. Note: All newlines in the docstring will be collapsed and mangle the long help text. Grouping of commands is not possible. Standard commands (for development) can't be customized under the same name or hidden. (Like for paster, the conceptual model also assumes that the sub-command naming is namespaced so commands from other packages won't conflict.) The usage help is fully automated from the declared options. For all deprecated Commands, replace paster hidden = True with gearbox deprecated = True Note: config_file, takes_config_file, min_args and max_args are not available / relevant. The gearbox parser is customized by overriding get_parser - there is nothing like paster update_parser. Gearbox is using argparse instead of optparse ... but argparse add_argument is mostly backwards compatible with optparse add_option. Instead of overriding command or run as in paster, override take_action in gearbox. The parsed arguments are passed to take_action, not available on the command instance. Paster BadCommand is not available and must be handled manually, terminating with sys.exit(1). There is no standard make-config command in gearbox. Paster appinstall has been replaced by the somewhat different setup_app module in gearbox. There is still no clean way to pass parameters to SetupAppCommand and it relies on websetup and other apparently unnecessary complexity. Instead, implement setup-db from scratch. Minor change by Thomas De Schampheleire: add gearbox logging configuration. Because we use logging.config.fileConfig(.inifile) during gearbox command execution, the logging settings need to be correct and contain a block for gearbox logging itself. Otherwise, errors in command processing are not even visible and the command exits silently.
author Mads Kiilerich <madski@unity3d.com>
date Tue, 25 Oct 2016 21:32:24 +0200
parents 60f9840c8df1
children 8152f9e6a778
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
60f9840c8df1 docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
21 Behavioral customization: rcextensions
60f9840c8df1 docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
22 --------------------------------------
60f9840c8df1 docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
23
60f9840c8df1 docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
24 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
25 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
26
60f9840c8df1 docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
27 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
28 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
29 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
30 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
31 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
32
60f9840c8df1 docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
33 To generate a skeleton extensions package, run::
60f9840c8df1 docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
34
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
35 gearbox make-rcext -c my.ini
5779
60f9840c8df1 docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
36
60f9840c8df1 docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
37 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
38 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
39 for more details.
60f9840c8df1 docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
40
60f9840c8df1 docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
41
60f9840c8df1 docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
42 Behavioral customization: code changes
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 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
46 in the source code.
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 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
49 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
50 details.