Mercurial Repository: p/roundup/code: doc/customizing.txt comparison

comparison doc/customizing.txt @ 6168:de9d602c8ce6

more index entries and CHANGES.txt update for them.

author	John Rouillard <rouilj@ieee.org>
date	Thu, 14 May 2020 22:18:18 -0400
parents	c2fd254c9257
children	53a674b5910f

comparison

equal deleted inserted replaced

-:81ae33038ec5
+:de9d602c8ce6
 Trackers in a Nutshell
 ======================
 Trackers have the following structure:
+.. index::
+single: tracker; structure db directory
+single: tracker; structure detectors directory
+single: tracker; structure extensions directory
+single: tracker; structure html directory
+single: tracker; structure html directory
+single: tracker; structure lib directory
 =================== ========================================================
 Tracker File        Description
 =================== ========================================================
 config.ini          Holds the basic `tracker configuration`_
 html/               Web interface templates, images and style sheets
 lib/                optional common imports for detectors and extensions
 =================== ========================================================
+.. index:: config.ini
+.. index:: configuration; see config.ini
 Tracker Configuration
 =====================
 The ``config.ini`` located in your tracker home contains the basic
 configuration for the web and e-mail components of roundup's interfaces.
 Example configuration settings are below. This is a partial
 list. Documentation on all the settings is included in the
 ``config.ini`` file.
-.. index:: configuration; sections main
+.. index:: config.ini; sections main
 Section **main**
 database -- ``db``
 Database directory path. The path may be either absolute or relative
 to the directory containig this config file.
 reader has a limit on the size of individual fields
 starting with python 2.5. Set this to a higher value if you
 get the error 'Error: field larger than field limit' during
 import.
+.. index:: config.ini; sections tracker
 Section **tracker**
 name -- ``Roundup issue tracker``
 A descriptive name for your roundup instance.
 web -- ``http://host.example/demo/``
 language -- default *blank*
 Default locale name for this tracker. If this option is not set, the
 language is determined by the environment variable LANGUAGE, LC_ALL,
 LC_MESSAGES, or LANG, in that order of preference.
-.. index:: configuration; sections web
+.. index:: config.ini; sections web
 Section **web**
 allow_html_file -- ``no``
 Setting this option enables Roundup to serve uploaded HTML
 file content *as HTML*. This is a potential security risk
 debug -- ``no``
 Setting this option makes Roundup display error tracebacks
 in the user's browser rather than emailing them to the
 tracker admin."),
+.. index:: config.ini; sections rdbms
+single: config.ini; database settings
 Section **rdbms**
 Settings in this section are used to set the backend and configure
 addition settings needed by RDBMs like SQLite, Postgresql and
 MySQL backends.
 cache_size -- `100`
 Size of the node cache (in elements) used to keep most recently used
 data in memory.
+.. index:: config.ini; sections logging
+see: logging; config.ini, sections logging
 Section **logging**
 config -- default *blank*
 Path to configuration file for standard Python logging module. If this
 option is set, logging configuration is loaded from specified file;
 options 'filename' and 'level' in this section are ignored. The path may
 level -- ``ERROR``
 Minimal severity level of messages written to log file. If above 'config'
 option is set, this option has no effect.
 Allowed values: ``DEBUG``, ``INFO``, ``WARNING``, ``ERROR``
+.. index:: config.ini; sections mail
 Section **mail**
 Outgoing email options. Used for nosy messages, password reset and
 registration approval requests.
 domain -- ``localhost``
 Add the mail address of the author to the author information at the
 top of all messages.  If this is false but add_authorinfo is true,
 only the name of the actor is added which protects the mail address
 of the actor from being exposed at mail archives, etc.
+.. index:: config.ini; sections mailgw
+single: mailgw; config
+see: mail gateway; mailgw
 Section **mailgw**
 Roundup Mail Gateway options
 keep_quoted_text -- ``yes``
 Keep email citations when accepting messages. Setting this to ``no`` strips
 text/plain part it finds. If this part is inside a
 multipart/alternative, and this option is set, all other
 parts of the multipart/alternative are ignored. The default
 is to keep all parts and attach them to the issue.
+.. index:: config.ini; sections php
 Section **pgp**
 OpenPGP mail processing options
 enable -- ``no``
 Enable PGP processing. Requires gpg.
 processing on. If not specified, it happens for all users.
 homedir -- default *blank*
 Location of PGP directory. Defaults to $HOME/.gnupg if not
 specified.
+.. index:: config.ini; sections nosy
 Section **nosy**
 Nosy messages sending
 messages_to_author -- ``no``
 Configuration variables may be referred to in lower or upper case. In code,
 variables not in the "main" section are referred to using their section and
 name, so "domain" in the section "mail" becomes MAIL_DOMAIN.
+.. index:: pair: configuration; extensions
+pair: configuration; detectors
 Extending the configuration file
 --------------------------------
 You can't add new variables to the config.ini file in the tracker home but
 you can add two new config.ini files:
 The initial_data.py module sets up the initial state of your
 tracker. It’s called exactly once - by the ``roundup-admin initialise``
 command. See the start of the section on database content for more
 info about how this works.
+.. index:: schema; classic - description of
 The "classic" schema
 --------------------
 The "classic" schema looks like this (see section `setkey(property)`_
 issue = IssueClass(db, "issue", keyword=Multilink("keyword"),
 status=Link("status"), assignedto=Link("user"),
 priority=Link("priority"))
 issue.setkey('title')
+.. index:: schema; allowed changes
 What you can't do to the schema
 -------------------------------
 You must never:
 The actual data entered into the database, using ``class.create()``, are
 called items. They have a special immutable property called ``'id'``. We
 sometimes refer to this as the *itemid*.
+.. index:: schema; property types
 Properties
 ~~~~~~~~~~
 A Class is comprised of one or more properties of the following types:
 class. The value is a list of integers.
 Properties can have additional attributes to change the default
 behaviour:
+.. index:: triple: schema; property attributes; required
+triple: schema; property attributes; default_value
+triple: schema; property attributes; quiet
 * All properties support the following attributes:
 - ``required``: see `design documentation`_. Adds the property to
 the list returned by calling get_required_props for the class.
 - ``default_value``: see `design documentation`_ Sets the default
 user). Making properties that are updated as an indirect result of
 a user's change (e.g. updating a blockers property, counting
 number of times an issue was reopened or reassigned etc.) should
 not be displayed to the user as they can be confusing.
+.. index:: triple: schema; property attributes; indexme
 * String properties can have an ``indexme`` attribute that defines if the
 property should be part of the full text index. The default is 'no' but this
 can be set to 'yes' to allow a property's contents to be in the full
 text index.
+.. index:: triple: schema; property attributes; use_double
 * Number properties can have a ``use_double`` attribute that, when set
 to ``True``, will use double precision floating point in the database.
 * Link and Multilink properties can have several attributes:
+.. index:: triple: schema; property attributes; do_journal
 - ``do_journal``: By default, every change of a link property is
 recorded in the item being linked to (or being unlinked). A typical
 use-case for setting ``do_journal='no'`` would be to turn off
 journalling of nosy list, message author and message recipient link
 and unlink events to prevent the journal from clogged with these
 events.
+.. index:: triple: schema; property attributes; try_id_parsing
 - ``try_id_parsing`` is turned on by default. If entering a number
 into a Link or Multilink field, roundup interprets this number as an
 ID of the item to link to. Sometimes items can have numeric names
 (like, e.g., product codes). For these roundup needs to match the
 numeric name and should never match an ID. In this case you can set
 ``try_id_parsing='no'``.
+.. index:: triple: schema; property attributes; rev_multilink
 - The ``rev_multilink`` option takes a property name to be inserted
 into the linked-to class. This property is a Multilink property that
 links back to the current class. The new Multilink is read-only (it
 is automatically modified if the Link or Multilink property defining
 it is modified). The new property can be used in normal searches
 		 assigned_to = Link("user", rev_multilink="responsibleFor"),
 		 ... )
 This makes it easy to list all issues that the user is responsible
 for (aka assigned_to).
+.. index:: triple: schema; property attributes; msg_header_property
 - The ``msg_header_property`` is used by the mail gateway when sending
 out messages. When a link or multilink property of an issue changes,
 roundup creates email headers of the form::
 for emails sent on issues where joe_user has been assigned to the issue.
 If this property is set to the empty string "", it will prevent
 the header from being generated on outgoing mail.
+.. index:: triple: schema; class property; creator
+triple: schema; class property; creation
+triple: schema; class property; actor
+triple: schema; class property; activity
 All Classes automatically have a number of properties by default:
 *creator*
 Link to the user that created the item.
 *creation*
 Link to the user that last modified the item.
 *activity*
 Date the item was last modified.
+.. index:: triple: schema; class property; content
+triple: schema; class property; type
 FileClass
 ~~~~~~~~~
 FileClasses save their "content" attribute off in a separate file from
 the rest of the database. This reduces the number of large entries in
 allows us to use command-line tools to operate on the files. They are
 stored in the files sub-directory of the ``'db'`` directory in your
 tracker. FileClasses also have a "type" attribute to store the MIME
 type of the file.
+.. index:: triple: schema; class property; messages
+triple: schema; class property; files
+triple: schema; class property; nosy
+triple: schema; class property; superseder
 IssueClass
 ~~~~~~~~~~
 IssueClasses automatically include the "messages", "files", "nosy", and
 created, and the value of the "activity" property is the date when any
 property on the item was last edited (equivalently, these are the dates
 on the first and last records in the item's journal). The "creator"
 property holds a link to the user that created the issue.
+.. index: triple: schema; class method; setkey
 setkey(property)
 ~~~~~~~~~~~~~~~~
 Select a String property of the class to be the key property. The key
 roundup-admin set issue23 assignedto=richard
 Note, the same thing can be done in the web and e-mail interfaces.
+.. index: triple: schema; class method; setlabelprop
 setlabelprop(property)
 ~~~~~~~~~~~~~~~~~~~~~~
 Select a property of the class to be the label property. The label
 property is used whereever an item should be uniquely identified, e.g.,
 You should make sure that users have View access to this property or
 the id property for a class. If the property can not be viewed by a
 user, looping over items in the class (e.g. messages attached to an
 issue) will not work.
+.. index: triple: schema; class method; setorderprop
 setorderprop(property)
 ~~~~~~~~~~~~~~~~~~~~~~
 Select a property of the class to be the order property. The order
 * the label property (see `setlabelprop(property)`_ above)
 So in most cases you can get away without specifying setorderprop
 explicitly.
+.. index: triple: schema; class method; create
 create(information)
 ~~~~~~~~~~~~~~~~~~~
 Create an item in the database. This is generally used to create items
 in the "definitional" classes like "priority" and "status".
+.. index: schema; item ordering
 A note about ordering
 ~~~~~~~~~~~~~~~~~~~~~
 When we sort items in the hyperdb, we use one of a number of methods,
 .. index:: detectors; writing api
 Detector API
 ------------
+.. index:: pair: detectors; auditors
+single: auditors; function signature
+single: auditors; defining
+single: auditors; arguments
 Auditors are called with the arguments::
 audit(db, cl, itemid, newdata)
 where ``db`` is the database, ``cl`` is an instance of Class or
 For a ``set()`` operation, newdata contains only the names and values of
 properties that are about to be changed.
 For a ``retire()`` or ``restore()`` operation, newdata is None.
+.. index:: pair: detectors; reactor
+single: reactors; function signature
+single: reactors; defining
+single: reactors; arguments
 Reactors are called with the arguments::
 react(db, cl, itemid, olddata)
 things with a .eml attachment, as they deem it 'unsafe'. Worse yet,
 they'll just give you an incomprehensible error message. For more
 information, see the detector code - it has a length explanation.
+.. index:: auditors; rules for use
+single: reactors; rules for use
 Auditor or Reactor?
 -------------------
 Generally speaking, the following rules should be observed:
 messages which only consist of a change note (ie. the message id parameter
 is not required - this is referred to as a "System Message" because it
 comes from "the system" and not a user).
+.. index:: extensions
+.. index:: extensions; add python functions to tracker
 Extensions - adding capabilities to your tracker
 ================================================
 .. _extensions:
 While detectors_ add new behavior by reacting to changes in tracked
 * a file named rss.xml will be cached for 5 minutes
 * a file named local.js will be cached for 2 hours
 Note that a file name match overrides the mime type settings.
 Example: Implement password complexity checking
 -----------------------------------------------
+.. index:: tracker; lib directory (example)
 This example uses the zxcvbn_ module that you can place in the zxcvbn
 subdirectory of your tracker's lib directory.
 If you add this to the interfaces.py file in the root directory of
 Changes to Tracker Behaviour
 ----------------------------
+.. index:: single: auditors; how to register (example)
+single: reactors; how to register (example)
 Preventing SPAM
 ~~~~~~~~~~~~~~~
 The following detector code may be installed in your tracker's
 ``detectors`` directory. It will block any messages being created that
 In the auditor, there is a loop over all users. For a site with
 only few users this will pose no serious problem; however, with
 many users this will be a serious performance bottleneck.
 A way out would be to link from the keywords to the users who
 selected these keywords as nosy keywords. This will eliminate the
-loop over all users.
+loop over all users. See the ``rev_multilink`` attribute to make
+this easier.
 Restricting updates that arrive by email
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Roundup supports multiple update methods:

Mercurial > p > roundup > code

comparison doc/customizing.txt @ 6168:de9d602c8ce6