Added better explanation of the instance configuration.

Also fixed the stylesheet to remove the extra whitespace in <dd> and <li>
first paras.

git-svn-id: http://svn.roundup-tracker.org/svnroot/roundup/trunk@808 57a73879-2fb5-44c3-a270-3262357dd7e2

diff --git a/doc/customizing.txt b/doc/customizing.txt
index ac9235eae789cddd80d6eb9290efddf2456658b1..0288dfceee6e5b1eb35f6f40cde50d1f89f2297e 100644 (file)
--- 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 789978cae4a9e74d7eab790f02e3f4b3459a138f..e2bfb08eb18f91c2bdb5499ffab59e53504161a5 100644 (file)
--- 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 ;