Mercurial > kallithea
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 |
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. |