From a2b16ffd818d5f2ecbe07b9d75cc95b0e840c332 Mon Sep 17 00:00:00 2001 From: richard Date: Mon, 24 Jun 2002 00:57:23 +0000 Subject: [PATCH] Added better explanation of the instance configuration. Also fixed the stylesheet to remove the extra whitespace in
and
  • first paras. git-svn-id: http://svn.roundup-tracker.org/svnroot/roundup/trunk@808 57a73879-2fb5-44c3-a270-3262357dd7e2 --- doc/customizing.txt | 370 ++++++++++++++++++++++++++++++++++---------- doc/default.css | 12 +- 2 files changed, 302 insertions(+), 80 deletions(-) diff --git a/doc/customizing.txt b/doc/customizing.txt index ac9235e..0288dfc 100644 --- a/doc/customizing.txt +++ b/doc/customizing.txt @@ -2,7 +2,7 @@ Customising Roundup =================== -:Version: $Revision: 1.7 $ +:Version: $Revision: 1.8 $ .. contents:: @@ -32,90 +32,304 @@ Instance Configuration The instance_config.py located in your instance home contains the basic configuration for the web and e-mail components of roundup's interfaces. This -file is a Python module. The default instance_config.py is given below - as you +file is a Python module. The configuration variables available are: + +**INSTANCE_HOME** - ``os.path.split(__file__)[0]`` + The instance home directory. The above default code will automatically + determine the instance home for you. + +**MAILHOST** - ``'localhost'`` + The SMTP mail host that roundup will use to send e-mail. + +**MAIL_DOMAIN** - ``'your.tracker.email.domain.example'`` + The domain name used for email addresses. + +**DATABASE** - ``os.path.join(INSTANCE_HOME, 'db')`` + This is the directory that the database is going to be stored in. By default + it is in the instance home. + +**TEMPLATES** - ``os.path.join(INSTANCE_HOME, 'html')`` + This is the directory that the HTML templates reside in. By default they are + in the instance home. + +**INSTANCE_NAME** - ``'Roundup issue tracker'`` + A descriptive name for your roundup instance. This is sent out in e-mails and + appears in the heading of CGI pages. + +**ISSUE_TRACKER_EMAIL** - ``'issue_tracker@%s'%MAIL_DOMAIN`` + The email address that e-mail sent to roundup should go to. Think of it as the + instance's personal e-mail address. + +**ISSUE_TRACKER_WEB** - ``'http://your.tracker.url.example/'`` + The web address that the instance is viewable at. This will be included in + information sent to users of the tracker. + +**ADMIN_EMAIL** - ``'roundup-admin@%s'%MAIL_DOMAIN`` + The email address that roundup will complain to if it runs into trouble. + +**FILTER_POSITION** - ``'top'``, ``'bottom'`` or ``'top and bottom'`` + Where to place the web filtering HTML on the index page. + +**ANONYMOUS_ACCESS** - ``'deny'`` or ``'allow'`` + Deny or allow anonymous access to the web interface. + +**ANONYMOUS_REGISTER** - ``'deny'`` or ``'allow'`` + Deny or allow anonymous users to register through the web interface. + +**ANONYMOUS_REGISTER_MAIL** - ``'deny'`` or ``'allow'`` + Deny or allow anonymous users to register through the mail interface. + +**MESSAGES_TO_AUTHOR** - ``'yes'`` or``'no'`` + Send nosy messages to the author of the message. + +**ADD_AUTHOR_TO_NOSY** - ``'new'``, ``'yes'`` or ``'no'`` + Does the author of a message get placed on the nosy list automatically? + If ``'new'`` is used, then the author will only be added when a message + creates a new issue. If ``'yes'``, then the author will be added on followups + too. If ``'no'``, they're never added to the nosy. + +**ADD_RECIPIENTS_TO_NOSY** - ``'new'``, ``'yes'`` or ``'no'`` + Do the recipients (To:, Cc:) of a message get placed on the nosy list? + If ``'new'`` is used, then the recipients will only be added when a message + creates a new issue. If ``'yes'``, then the recipients will be added on + followups too. If ``'no'``, they're never added to the nosy. + +**EMAIL_SIGNATURE_POSITION** - ``'top'``, ``'bottom'`` or ``'none'`` + Where to place the email signature in messages that Roundup generates. + +**EMAIL_KEEP_QUOTED_TEXT** - ``'yes'`` or ``'no'`` + Keep email citations. Citations are the part of e-mail which the sender has + quoted in their reply to previous e-mail. + +**EMAIL_LEAVE_BODY_UNCHANGED** - ``'no'`` + Preserve the email body as is. Enabiling this will cause the entire message + body to be stored, including all citations and signatures. It should be + either ``'yes'`` or ``'no'``. + +**MAIL_DEFAULT_CLASS** - ``'issue'`` or ``''`` + Default class to use in the mailgw if one isn't supplied in email + subjects. To disable, comment out the variable below or leave it blank. + +**HEADER_INDEX_LINKS** - ``['DEFAULT', 'UNASSIGNED', 'USER']`` + Define what index links are available in the header, and what their + labels are. Each key is used to look up one of the index specifications + below - so ``'DEFAULT'`` will use ``'DEFAULT_INDEX'``. + + Example ``DEFAULT_INDEX``:: + + { + 'LABEL': 'All Issues', + 'CLASS': 'issue', + 'SORT': ['-activity'], + 'GROUP': ['priority'], + 'FILTER': ['status'], + 'COLUMNS': ['id','activity','title','creator','assignedto'], + 'FILTERSPEC': { + 'status': ['-1', '1', '2', '3', '4', '5', '6', '7'], + }, + } + + This defines one of the index links that appears in the + ``HEADER_INDEX_LINKS`` list. + + **LABEL** - ``'All Issues'`` + The text that appears as the link label. + **CLASS** - ``'issue'`` + The class to display the index for. + **SORT** - ``['-activity']`` + Sort by prop name, optionally preceeded with '-' to give descending or + nothing for ascending sorting. + **GROUP** - ``['priority']`` + Group by prop name, optionally preceeded with '-' or to sort in descending + or nothing for ascending order. + **FILTER** - ``['status']`` + Selects which props should be displayed in the filter section. + Default is all. + **COLUMNS** - ``['id','activity','title','creator','assignedto']`` + Selects the columns that should be displayed. Default is all. + **FILTERSPEC** - *a dictionary giving the filter specification* + The ``FILTERSPEC`` gives the filtering arguments. This selects the values + the node properties given by propname must have. + + Where the ``FILTERSPEC`` value is ``'CURRENT USER'``, it will be replaced + by the id of the logged-in user. For example:: + + 'FILTERSPEC': { + 'status': ['-1', '1', '2', '3', '4', '5', '6', '7'], + 'assignedto': 'CURRENT USER', + }, + +**HEADER_ADD_LINKS** - ``['issue']`` + List the classes that users are able to add nodes to. + +**HEADER_SEARCH_LINKS** - ``['issue']`` + List the classes that users can search. + +**SEARCH_FILTERS** - ``['ISSUE_FILTER', 'SUPPORT_FILTER']`` + List search filters per class. Like the INDEX entries above, each key is + used to look up one of the filter specifications below - so ``'ISSUE'`` + will use ``'ISSUE_FILTER'``. + + Example ``ISSUE_FILTER``:: + + ISSUE_FILTER = { + 'CLASS': 'issue', + 'FILTER': ['status', 'priority', 'assignedto', 'creator'] + } + + **CLASS** - ``'issue'`` + The class that the search page is for. + **FILTER** - ``['status', 'priority', 'assignedto', 'creator']`` + Selects which props should be displayed on the filter page. Default is + all. + +The default instance_config.py is given below - as you can see, the MAIL_DOMAIN must be edited before any interaction with the instance is attempted.:: - MAIL_DOMAIN=MAILHOST=HTTP_HOST=None - HTTP_PORT=0 - - # roundup home is this package's directory - INSTANCE_HOME=os.path.split(__file__)[0] - - # The SMTP mail host that roundup will use to send mail - if not MAILHOST: - MAILHOST = 'localhost' - - # The domain name used for email addresses. - if not MAIL_DOMAIN: - MAIL_DOMAIN = 'fill.me.in.' - - # the next two are only used for the standalone HTTP server. - if not HTTP_HOST: - HTTP_HOST = '' - if not HTTP_PORT: - HTTP_PORT = 9080 - - # This is the directory that the database is going to be stored in - DATABASE = os.path.join(INSTANCE_HOME, 'db') - - # This is the directory that the HTML templates reside in - TEMPLATES = os.path.join(INSTANCE_HOME, 'html') - - # The email address that mail to roundup should go to - ISSUE_TRACKER_EMAIL = 'issue_tracker@%s'%MAIL_DOMAIN - - # The web address that the instance is viewable at - ISSUE_TRACKER_WEB = 'http://some.useful.url/' - - # The email address that roundup will complain to if it runs into trouble - ADMIN_EMAIL = 'roundup-admin@%s'%MAIL_DOMAIN - - # Somewhere for roundup to log stuff internally sent to stdout or stderr - LOG = os.path.join(INSTANCE_HOME, 'roundup.log') - - # Where to place the web filtering HTML on the index page - FILTER_POSITION = 'bottom' # one of 'top', 'bottom', 'top and bottom' - - # Deny or allow anonymous access to the web interface - ANONYMOUS_ACCESS = 'deny' # either 'deny' or 'allow' - - # Deny or allow anonymous users to register through the web interface - ANONYMOUS_REGISTER = 'deny' # either 'deny' or 'allow' - - # Deny or allow anonymous users to register through the mail interface - ANONYMOUS_REGISTER_MAIL = 'deny' # either 'deny' or 'allow' - - # Send nosy messages to the author of the message - MESSAGES_TO_AUTHOR = 'no' # either 'yes' or 'no' - - # Does the author of a message get placed on the nosy list automatically? - # If 'new' is used, then the author will only be added when a message - # creates a new issue. If 'yes', then the author will be added on followups - # too. If 'no', they're never added to the nosy. - ADD_AUTHOR_TO_NOSY = 'new' # one of 'yes', 'no', 'new' - - # Do the recipients (To:, Cc:) of a message get placed on the nosy list? - # If 'new' is used, then the recipients will only be added when a message - # creates a new issue. If 'yes', then the recipients will be added on - # followups - # too. If 'no', they're never added to the nosy. - ADD_RECIPIENTS_TO_NOSY = 'new' # either 'yes', 'no', 'new' + # roundup home is this package's directory + INSTANCE_HOME=os.path.split(__file__)[0] - # Where to place the email signature - EMAIL_SIGNATURE_POSITION = 'bottom' # one of 'top', 'bottom', 'none' + # The SMTP mail host that roundup will use to send mail + MAILHOST = 'localhost' - # Keep email citations - EMAIL_KEEP_QUOTED_TEXT = 'no' # either 'yes' or 'no' + # The domain name used for email addresses. + MAIL_DOMAIN = 'your.tracker.email.domain.example' - # Preserve the email body as is - EMAIL_LEAVE_BODY_UNCHANGED = 'no' # either 'yes' or 'no' + # the next two are only used for the standalone HTTP server. + HTTP_HOST = '' + HTTP_PORT = 9080 - # Default class to use in the mailgw if one isn't supplied in email - # subjects. To disable, comment out the variable below or leave it blank. - # Examples: - MAIL_DEFAULT_CLASS = 'issue' # use "issue" class by default - #MAIL_DEFAULT_CLASS = '' # disable (or just comment the var out) + # This is the directory that the database is going to be stored in + DATABASE = os.path.join(INSTANCE_HOME, 'db') + + # This is the directory that the HTML templates reside in + TEMPLATES = os.path.join(INSTANCE_HOME, 'html') + + # A descriptive name for your roundup instance + INSTANCE_NAME = 'Roundup issue tracker' + + # The email address that mail to roundup should go to + ISSUE_TRACKER_EMAIL = 'issue_tracker@%s'%MAIL_DOMAIN + + # The web address that the instance is viewable at + ISSUE_TRACKER_WEB = 'http://your.tracker.url.example/' + + # The email address that roundup will complain to if it runs into trouble + ADMIN_EMAIL = 'roundup-admin@%s'%MAIL_DOMAIN + + # Somewhere for roundup to log stuff internally sent to stdout or stderr + LOG = os.path.join(INSTANCE_HOME, 'roundup.log') + + # Where to place the web filtering HTML on the index page + FILTER_POSITION = 'bottom' # one of 'top', 'bottom', 'top and bottom' + + # Deny or allow anonymous access to the web interface + ANONYMOUS_ACCESS = 'deny' # either 'deny' or 'allow' + + # Deny or allow anonymous users to register through the web interface + ANONYMOUS_REGISTER = 'deny' # either 'deny' or 'allow' + + # Deny or allow anonymous users to register through the mail interface + ANONYMOUS_REGISTER_MAIL = 'deny' # either 'deny' or 'allow' + + # Send nosy messages to the author of the message + MESSAGES_TO_AUTHOR = 'no' # either 'yes' or 'no' + + # Does the author of a message get placed on the nosy list automatically? + # If 'new' is used, then the author will only be added when a message + # creates a new issue. If 'yes', then the author will be added on followups + # too. If 'no', they're never added to the nosy. + ADD_AUTHOR_TO_NOSY = 'new' # one of 'yes', 'no', 'new' + + # Do the recipients (To:, Cc:) of a message get placed on the nosy list? + # If 'new' is used, then the recipients will only be added when a message + # creates a new issue. If 'yes', then the recipients will be added on followups + # too. If 'no', they're never added to the nosy. + ADD_RECIPIENTS_TO_NOSY = 'new' # either 'yes', 'no', 'new' + + # Where to place the email signature + EMAIL_SIGNATURE_POSITION = 'bottom' # one of 'top', 'bottom', 'none' + + # Keep email citations + EMAIL_KEEP_QUOTED_TEXT = 'no' # either 'yes' or 'no' + + # Preserve the email body as is + EMAIL_LEAVE_BODY_UNCHANGED = 'no' # either 'yes' or 'no' + + # Default class to use in the mailgw if one isn't supplied in email + # subjects. To disable, comment out the variable below or leave it blank. + # Examples: + MAIL_DEFAULT_CLASS = 'issue' # use "issue" class by default + #MAIL_DEFAULT_CLASS = '' # disable (or just comment the var out) + + # Define what index links are available in the header, and what their + # labels are. Each key is used to look up one of the index specifications + # below - so 'DEFAULT' will use 'DEFAULT_INDEX'. + # Where the FILTERSPEC has 'assignedto' with a value of None, it will be + # replaced by the id of the logged-in user. + HEADER_INDEX_LINKS = ['DEFAULT', 'UNASSIGNED', 'USER'] + + # list the classes that users are able to add nodes to + HEADER_ADD_LINKS = ['issue'] + + # list the classes that users can search + HEADER_SEARCH_LINKS = ['issue'] + + # list search filters per class + SEARCH_FILTERS = ['ISSUE_FILTER', 'SUPPORT_FILTER'] + + # Now the DEFAULT display specification. TODO: describe format + DEFAULT_INDEX = { + 'LABEL': 'All Issues', + 'CLASS': 'issue', + 'SORT': ['-activity'], + 'GROUP': ['priority'], + 'FILTER': ['status'], + 'COLUMNS': ['id','activity','title','creator','assignedto'], + 'FILTERSPEC': { + 'status': ['-1', '1', '2', '3', '4', '5', '6', '7'], + }, + } + + # The "unsassigned issues" index + UNASSIGNED_INDEX = { + 'LABEL': 'Unassigned Issues', + 'CLASS': 'issue', + 'SORT': ['-activity'], + 'GROUP': ['priority'], + 'FILTER': ['status', 'assignedto'], + 'COLUMNS': ['id','activity','title','creator','status'], + 'FILTERSPEC': { + 'status': ['-1', '1', '2', '3', '4', '5', '6', '7'], + 'assignedto': ['-1'], + }, + } + + # The "my issues" index -- note that the user's id will replace the + # 'CURRENT USER' value of the "assignedto" filterspec + USER_INDEX = { + 'LABEL': 'My Issues', + 'CLASS': 'issue', + 'SORT': ['-activity'], + 'GROUP': ['priority'], + 'FILTER': ['status', 'assignedto'], + 'COLUMNS': ['id','activity','title','creator','status'], + 'FILTERSPEC': { + 'status': ['-1', '1', '2', '3', '4', '5', '6', '7'], + 'assignedto': 'CURRENT USER', + }, + } + + ISSUE_FILTER = { + 'CLASS': 'issue', + 'FILTER': ['status', 'priority', 'assignedto', 'creator'] + } + + SUPPORT_FILTER = { + 'CLASS': 'issue', + 'FILTER': ['status', 'priority', 'assignedto', 'creator'] + } Instance Schema diff --git a/doc/default.css b/doc/default.css index 789978c..e2bfb08 100644 --- a/doc/default.css +++ b/doc/default.css @@ -1,8 +1,8 @@ /* :Author: David Goodger :Contact: goodger@users.sourceforge.net -:date: $Date: 2002-05-24 03:12:39 $ -:version: $Revision: 1.4 $ +:date: $Date: 2002-06-24 00:57:23 $ +:version: $Revision: 1.5 $ :copyright: This stylesheet has been placed in the public domain. Default cascading style sheet for the HTML output of Docutils. @@ -114,6 +114,14 @@ p.label { p.topic-title { font-weight: bold } +dd p:first-child { + margin-top: 0px; +} + +li p:first-child { + margin-top: 0px; +} + pre.literal-block, pre.doctest-block { margin-left: 2em ; margin-right: 2em ; -- 2.30.2