Mercurial > p > roundup > code

comparison doc/customizing.txt @ 6163:c2fd254c9257

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Doc updates/indexing. doc/admin_guide.txt, doc/customizing.txt, doc/features.txt, doc/installation.txt, doc/mysql.txt, doc/postgresql.txt: adding index entries doc/customizing.txt: reference schema changes later in document in addition to wiki. website/www/contents.txt: make wiki url https:.... Remove indices/tables as they don't show up in web interface. Put docs/announcement.txt into hidden toctree to silence warning from sphinx. Announcement.txt is referenced from index.txt so can't silence by adding to conf.py exclude_patern. website/www/index.txt: mention security and other improvements in jinja2 templates. website/www/conf.py: get rid of all warning by using exclude_patterns to ignore docs that aren't included. Remove exclude_trees using exclude_pattern instead. Make html_add_permalinks value acceptable so no warning reported. website/www/_static/style.css, website/www/_templtes/layout.html: add prev/next/index links for all doc pages.
author John Rouillard <rouilj@ieee.org>
date Wed, 13 May 2020 00:40:14 -0400
parents 9619d64c0351
children de9d602c8ce6
comparison
equal deleted inserted replaced
6162:9cfdbfc6d8ed 6163:c2fd254c9257
66 schema`_. Some configuration is also performed using permissions - see the 66 schema`_. Some configuration is also performed using permissions - see the
67 `security / access controls`_ section. For example, to allow users to 67 `security / access controls`_ section. For example, to allow users to
68 automatically register through the email interface, you must grant the 68 automatically register through the email interface, you must grant the
69 "Anonymous" Role the "Email Access" Permission. 69 "Anonymous" Role the "Email Access" Permission.
70 70
71 .. index:: configuration; sections 71 .. index::
72 single: config.ini; sections
73 see: configuration; config.ini
72 74
73 The following is taken from the `Python Library Reference`__ (July 18, 2018) 75 The following is taken from the `Python Library Reference`__ (July 18, 2018)
74 section "ConfigParser -- Configuration file parser": 76 section "ConfigParser -- Configuration file parser":
75 77
76 The configuration file consists of sections, led by a [section] header 78 The configuration file consists of sections, led by a [section] header
234 Section **rdbms** 236 Section **rdbms**
235 Settings in this section are used to set the backend and configure 237 Settings in this section are used to set the backend and configure
236 addition settings needed by RDBMs like SQLite, Postgresql and 238 addition settings needed by RDBMs like SQLite, Postgresql and
237 MySQL backends. 239 MySQL backends.
238 240
241 .. index::
242 single: postgres; select backend in config.ini
243 single: mysql; select backend in config.ini
244 single: sqlite; select backend in config.ini
245 single: anydbm; select backend in config.ini
246 see: database; postgres
247 see: database; mysql
248 see: database; sqlite
249 see: database; anydbm
250
239 backend -- set to value by init 251 backend -- set to value by init
240 The database backend such as anydbm, sqlite, mysql or postgres. 252 The database backend such as anydbm, sqlite, mysql or postgres.
241 253
242 name -- ``roundup`` 254 name -- ``roundup``
243 Name of the database to use. 255 Name of the database to use.
260 Name of the MySQL defaults file. Only used in MySQL connections. 272 Name of the MySQL defaults file. Only used in MySQL connections.
261 273
262 read_default_group -- ``roundup`` 274 read_default_group -- ``roundup``
263 Name of the group to use in the MySQL defaults file. Only used in 275 Name of the group to use in the MySQL defaults file. Only used in
264 MySQL connections. 276 MySQL connections.
277
278 .. index::
279 single: sqlite; lock timeout
265 280
266 sqlite_timeout -- ``30`` 281 sqlite_timeout -- ``30``
267 Number of seconds to wait when the SQLite database is locked. 282 Number of seconds to wait when the SQLite database is locked.
268 Used only for SQLite. 283 Used only for SQLite.
269 284
485 Attachments larger than the given number of bytes won't be attached 500 Attachments larger than the given number of bytes won't be attached
486 to nosy mails. They will be replaced by a link to the tracker's 501 to nosy mails. They will be replaced by a link to the tracker's
487 download page for the file. 502 download page for the file.
488 503
489 504
505 .. index:: single: roundup-admin; config.ini update
506 single: roundup-admin; config.ini create
507 single: config.ini; create
508 single: config.ini; update
509
490 You may generate a new default config file using the ``roundup-admin 510 You may generate a new default config file using the ``roundup-admin
491 genconfig`` command. You can generate a new config file merging in 511 genconfig`` command. You can generate a new config file merging in
492 existing settings using the ``roundup-admin updateconfig`` command. 512 existing settings using the ``roundup-admin updateconfig`` command.
493 513
494 Configuration variables may be referred to in lower or upper case. In code, 514 Configuration variables may be referred to in lower or upper case. In code,
521 [qa] 541 [qa]
522 recipients = email@example.com 542 recipients = email@example.com
523 543
524 then the above ``db.config.detectors['QA_RECIPIENTS']`` will still work. 544 then the above ``db.config.detectors['QA_RECIPIENTS']`` will still work.
525 545
526 .. index:: schema 546 .. index:: ! schema
527 547
528 Tracker Schema 548 Tracker Schema
529 ============== 549 ==============
530 550
531 .. note:: 551 .. note::
993 1013
994 1014
995 Examples of adding to your schema 1015 Examples of adding to your schema
996 --------------------------------- 1016 ---------------------------------
997 1017
998 The `Roundup wiki`_ has examples of 1018 Some examples are in the :ref:`CustomExamples` section below.
999 how schemas can be customised to add new functionality. 1019
1020 Also the `Roundup wiki`_ has additional examples of how schemas can be
1021 customised to add new functionality.
1000 1022
1001 .. _Roundup wiki: 1023 .. _Roundup wiki:
1002 https://wiki.roundup-tracker.org/ 1024 https://wiki.roundup-tracker.org/
1003 1025
1026 .. index:: !detectors
1004 1027
1005 Detectors - adding behaviour to your tracker 1028 Detectors - adding behaviour to your tracker
1006 ============================================ 1029 ============================================
1007 .. _detectors: 1030 .. _detectors:
1008 1031
1014 (**reactors**) changes to the contents of your database. They are Python 1037 (**reactors**) changes to the contents of your database. They are Python
1015 modules that sit in your tracker's ``detectors`` directory. You will 1038 modules that sit in your tracker's ``detectors`` directory. You will
1016 have some installed by default - have a look. You can write new 1039 have some installed by default - have a look. You can write new
1017 detectors or modify the existing ones. The existing detectors installed 1040 detectors or modify the existing ones. The existing detectors installed
1018 for you are: 1041 for you are:
1042
1043 .. index:: detectors; installed
1019 1044
1020 **nosyreaction.py** 1045 **nosyreaction.py**
1021 This provides the automatic nosy list maintenance and email sending. 1046 This provides the automatic nosy list maintenance and email sending.
1022 The nosy reactor (``nosyreaction``) fires when new messages are added 1047 The nosy reactor (``nosyreaction``) fires when new messages are added
1023 to issues. The nosy auditor (``updatenosy``) fires when issues are 1048 to issues. The nosy auditor (``updatenosy``) fires when issues are
1043 interface for detectors. 1068 interface for detectors.
1044 1069
1045 __ design.html 1070 __ design.html
1046 1071
1047 1072
1073 .. index:: detectors; writing api
1074
1048 Detector API 1075 Detector API
1049 ------------ 1076 ------------
1050 1077
1051 Auditors are called with the arguments:: 1078 Auditors are called with the arguments::
1052 1079
1080 values of properties that were changed. 1107 values of properties that were changed.
1081 1108
1082 For a ``retire()`` or ``restore()`` operation, ``itemid`` is the id of 1109 For a ``retire()`` or ``restore()`` operation, ``itemid`` is the id of
1083 the retired or restored item and ``olddata`` is None. 1110 the retired or restored item and ``olddata`` is None.
1084 1111
1112 .. index:: detectors; additional
1085 1113
1086 Additional Detectors Ready For Use 1114 Additional Detectors Ready For Use
1087 ---------------------------------- 1115 ----------------------------------
1088 1116
1089 Sample additional detectors that have been found useful will appear in 1117 Sample additional detectors that have been found useful will appear in
1609 # Allow anonymous users access to create or edit "issue" items (and the 1637 # Allow anonymous users access to create or edit "issue" items (and the
1610 # related file and message items) 1638 # related file and message items)
1611 #for cl in 'issue', 'file', 'msg': 1639 #for cl in 'issue', 'file', 'msg':
1612 # db.security.addPermissionToRole('Anonymous', 'Create', cl) 1640 # db.security.addPermissionToRole('Anonymous', 'Create', cl)
1613 # db.security.addPermissionToRole('Anonymous', 'Edit', cl) 1641 # db.security.addPermissionToRole('Anonymous', 'Edit', cl)
1642
1643 .. index::
1644 single: roundup-admin; class permissions
1614 1645
1615 You can use ``roundup-admin security`` to verify the permissions 1646 You can use ``roundup-admin security`` to verify the permissions
1616 defined in the schema. It also verifies that properties specified in 1647 defined in the schema. It also verifies that properties specified in
1617 permissions are valid for the class. This helps detect typos that can 1648 permissions are valid for the class. This helps detect typos that can
1618 cause baffling permission issues. 1649 cause baffling permission issues.
3753 tal:attributes="content string:text/html;; charset=${request/client/charset}" 3784 tal:attributes="content string:text/html;; charset=${request/client/charset}"
3754 /> 3785 />
3755 3786
3756 The charset is also sent in the http header. 3787 The charset is also sent in the http header.
3757 3788
3789 .. _CustomExamples:
3758 3790
3759 Examples 3791 Examples
3760 ======== 3792 ========
3761 3793
3762 .. contents:: 3794 .. contents::
3780 3812
3781 You add new fields by editing the ``schema.py`` file in you tracker's home. 3813 You add new fields by editing the ``schema.py`` file in you tracker's home.
3782 Schema changes are automatically applied to the database on the next 3814 Schema changes are automatically applied to the database on the next
3783 tracker access (note that roundup-server would need to be restarted as it 3815 tracker access (note that roundup-server would need to be restarted as it
3784 caches the schema). 3816 caches the schema).
3817
3818 .. index:: schema; example changes
3785 3819
3786 1. Modify the ``schema.py``:: 3820 1. Modify the ``schema.py``::
3787 3821
3788 issue = IssueClass(db, "issue", 3822 issue = IssueClass(db, "issue",
3789 assignedto=Link("user"), keyword=Multilink("keyword"), 3823 assignedto=Link("user"), keyword=Multilink("keyword"),
4279 db.security.addPermissionToRole('User', 'View', 'timelog') 4313 db.security.addPermissionToRole('User', 'View', 'timelog')
4280 4314
4281 If users are also able to *edit* timelog entries, then also include:: 4315 If users are also able to *edit* timelog entries, then also include::
4282 4316
4283 db.security.addPermissionToRole('User', 'Edit', 'timelog') 4317 db.security.addPermissionToRole('User', 'Edit', 'timelog')
4318
4319 .. index:: schema; example changes
4284 4320
4285 2. Link to the new class from your issue class (again, in 4321 2. Link to the new class from your issue class (again, in
4286 ``schema.py``):: 4322 ``schema.py``)::
4287 4323
4288 issue = IssueClass(db, "issue", 4324 issue = IssueClass(db, "issue",
Roundup Issue Tracker: http://roundup-tracker.org/