Skip to content

Commit b36356d

Browse files
author
Richard Jones
committed
Added better explanation of the instance configuration.
Also fixed the stylesheet to remove the extra whitespace in <dd> and <li> first paras.
1 parent 63c1600 commit b36356d

File tree

2 files changed

+302
-80
lines changed

2 files changed

+302
-80
lines changed

‎doc/customizing.txt‎

Lines changed: 292 additions & 78 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
Customising Roundup
33
===================
44

5-
:Version: $Revision: 1.7 $
5+
:Version: $Revision: 1.8 $
66

77
.. contents::
88

@@ -32,90 +32,304 @@ Instance Configuration
3232

3333
The instance_config.py located in your instance home contains the basic
3434
configuration for the web and e-mail components of roundup's interfaces. This
35-
file is a Python module. The default instance_config.py is given below - as you
35+
file is a Python module. The configuration variables available are:
36+
37+
**INSTANCE_HOME** - ``os.path.split(__file__)[0]``
38+
The instance home directory. The above default code will automatically
39+
determine the instance home for you.
40+
41+
**MAILHOST** - ``'localhost'``
42+
The SMTP mail host that roundup will use to send e-mail.
43+
44+
**MAIL_DOMAIN** - ``'your.tracker.email.domain.example'``
45+
The domain name used for email addresses.
46+
47+
**DATABASE** - ``os.path.join(INSTANCE_HOME, 'db')``
48+
This is the directory that the database is going to be stored in. By default
49+
it is in the instance home.
50+
51+
**TEMPLATES** - ``os.path.join(INSTANCE_HOME, 'html')``
52+
This is the directory that the HTML templates reside in. By default they are
53+
in the instance home.
54+
55+
**INSTANCE_NAME** - ``'Roundup issue tracker'``
56+
A descriptive name for your roundup instance. This is sent out in e-mails and
57+
appears in the heading of CGI pages.
58+
59+
**ISSUE_TRACKER_EMAIL** - ``'issue_tracker@%s'%MAIL_DOMAIN``
60+
The email address that e-mail sent to roundup should go to. Think of it as the
61+
instance's personal e-mail address.
62+
63+
**ISSUE_TRACKER_WEB** - ``'http://your.tracker.url.example/'``
64+
The web address that the instance is viewable at. This will be included in
65+
information sent to users of the tracker.
66+
67+
**ADMIN_EMAIL** - ``'roundup-admin@%s'%MAIL_DOMAIN``
68+
The email address that roundup will complain to if it runs into trouble.
69+
70+
**FILTER_POSITION** - ``'top'``, ``'bottom'`` or ``'top and bottom'``
71+
Where to place the web filtering HTML on the index page.
72+
73+
**ANONYMOUS_ACCESS** - ``'deny'`` or ``'allow'``
74+
Deny or allow anonymous access to the web interface.
75+
76+
**ANONYMOUS_REGISTER** - ``'deny'`` or ``'allow'``
77+
Deny or allow anonymous users to register through the web interface.
78+
79+
**ANONYMOUS_REGISTER_MAIL** - ``'deny'`` or ``'allow'``
80+
Deny or allow anonymous users to register through the mail interface.
81+
82+
**MESSAGES_TO_AUTHOR** - ``'yes'`` or``'no'``
83+
Send nosy messages to the author of the message.
84+
85+
**ADD_AUTHOR_TO_NOSY** - ``'new'``, ``'yes'`` or ``'no'``
86+
Does the author of a message get placed on the nosy list automatically?
87+
If ``'new'`` is used, then the author will only be added when a message
88+
creates a new issue. If ``'yes'``, then the author will be added on followups
89+
too. If ``'no'``, they're never added to the nosy.
90+
91+
**ADD_RECIPIENTS_TO_NOSY** - ``'new'``, ``'yes'`` or ``'no'``
92+
Do the recipients (To:, Cc:) of a message get placed on the nosy list?
93+
If ``'new'`` is used, then the recipients will only be added when a message
94+
creates a new issue. If ``'yes'``, then the recipients will be added on
95+
followups too. If ``'no'``, they're never added to the nosy.
96+
97+
**EMAIL_SIGNATURE_POSITION** - ``'top'``, ``'bottom'`` or ``'none'``
98+
Where to place the email signature in messages that Roundup generates.
99+
100+
**EMAIL_KEEP_QUOTED_TEXT** - ``'yes'`` or ``'no'``
101+
Keep email citations. Citations are the part of e-mail which the sender has
102+
quoted in their reply to previous e-mail.
103+
104+
**EMAIL_LEAVE_BODY_UNCHANGED** - ``'no'``
105+
Preserve the email body as is. Enabiling this will cause the entire message
106+
body to be stored, including all citations and signatures. It should be
107+
either ``'yes'`` or ``'no'``.
108+
109+
**MAIL_DEFAULT_CLASS** - ``'issue'`` or ``''``
110+
Default class to use in the mailgw if one isn't supplied in email
111+
subjects. To disable, comment out the variable below or leave it blank.
112+
113+
**HEADER_INDEX_LINKS** - ``['DEFAULT', 'UNASSIGNED', 'USER']``
114+
Define what index links are available in the header, and what their
115+
labels are. Each key is used to look up one of the index specifications
116+
below - so ``'DEFAULT'`` will use ``'DEFAULT_INDEX'``.
117+
118+
Example ``DEFAULT_INDEX``::
119+
120+
{
121+
'LABEL': 'All Issues',
122+
'CLASS': 'issue',
123+
'SORT': ['-activity'],
124+
'GROUP': ['priority'],
125+
'FILTER': ['status'],
126+
'COLUMNS': ['id','activity','title','creator','assignedto'],
127+
'FILTERSPEC': {
128+
'status': ['-1', '1', '2', '3', '4', '5', '6', '7'],
129+
},
130+
}
131+
132+
This defines one of the index links that appears in the
133+
``HEADER_INDEX_LINKS`` list.
134+
135+
**LABEL** - ``'All Issues'``
136+
The text that appears as the link label.
137+
**CLASS** - ``'issue'``
138+
The class to display the index for.
139+
**SORT** - ``['-activity']``
140+
Sort by prop name, optionally preceeded with '-' to give descending or
141+
nothing for ascending sorting.
142+
**GROUP** - ``['priority']``
143+
Group by prop name, optionally preceeded with '-' or to sort in descending
144+
or nothing for ascending order.
145+
**FILTER** - ``['status']``
146+
Selects which props should be displayed in the filter section.
147+
Default is all.
148+
**COLUMNS** - ``['id','activity','title','creator','assignedto']``
149+
Selects the columns that should be displayed. Default is all.
150+
**FILTERSPEC** - *a dictionary giving the filter specification*
151+
The ``FILTERSPEC`` gives the filtering arguments. This selects the values
152+
the node properties given by propname must have.
153+
154+
Where the ``FILTERSPEC`` value is ``'CURRENT USER'``, it will be replaced
155+
by the id of the logged-in user. For example::
156+
157+
'FILTERSPEC': {
158+
'status': ['-1', '1', '2', '3', '4', '5', '6', '7'],
159+
'assignedto': 'CURRENT USER',
160+
},
161+
162+
**HEADER_ADD_LINKS** - ``['issue']``
163+
List the classes that users are able to add nodes to.
164+
165+
**HEADER_SEARCH_LINKS** - ``['issue']``
166+
List the classes that users can search.
167+
168+
**SEARCH_FILTERS** - ``['ISSUE_FILTER', 'SUPPORT_FILTER']``
169+
List search filters per class. Like the INDEX entries above, each key is
170+
used to look up one of the filter specifications below - so ``'ISSUE'``
171+
will use ``'ISSUE_FILTER'``.
172+
173+
Example ``ISSUE_FILTER``::
174+
175+
ISSUE_FILTER = {
176+
'CLASS': 'issue',
177+
'FILTER': ['status', 'priority', 'assignedto', 'creator']
178+
}
179+
180+
**CLASS** - ``'issue'``
181+
The class that the search page is for.
182+
**FILTER** - ``['status', 'priority', 'assignedto', 'creator']``
183+
Selects which props should be displayed on the filter page. Default is
184+
all.
185+
186+
The default instance_config.py is given below - as you
36187
can see, the MAIL_DOMAIN must be edited before any interaction with the
37188
instance is attempted.::
38189

39-
MAIL_DOMAIN=MAILHOST=HTTP_HOST=None
40-
HTTP_PORT=0
41-
42-
# roundup home is this package's directory
43-
INSTANCE_HOME=os.path.split(__file__)[0]
44-
45-
# The SMTP mail host that roundup will use to send mail
46-
if not MAILHOST:
47-
MAILHOST = 'localhost'
48-
49-
# The domain name used for email addresses.
50-
if not MAIL_DOMAIN:
51-
MAIL_DOMAIN = 'fill.me.in.'
52-
53-
# the next two are only used for the standalone HTTP server.
54-
if not HTTP_HOST:
55-
HTTP_HOST = ''
56-
if not HTTP_PORT:
57-
HTTP_PORT = 9080
58-
59-
# This is the directory that the database is going to be stored in
60-
DATABASE = os.path.join(INSTANCE_HOME, 'db')
61-
62-
# This is the directory that the HTML templates reside in
63-
TEMPLATES = os.path.join(INSTANCE_HOME, 'html')
64-
65-
# The email address that mail to roundup should go to
66-
ISSUE_TRACKER_EMAIL = 'issue_tracker@%s'%MAIL_DOMAIN
67-
68-
# The web address that the instance is viewable at
69-
ISSUE_TRACKER_WEB = 'http://some.useful.url/'
70-
71-
# The email address that roundup will complain to if it runs into trouble
72-
ADMIN_EMAIL = 'roundup-admin@%s'%MAIL_DOMAIN
73-
74-
# Somewhere for roundup to log stuff internally sent to stdout or stderr
75-
LOG = os.path.join(INSTANCE_HOME, 'roundup.log')
76-
77-
# Where to place the web filtering HTML on the index page
78-
FILTER_POSITION = 'bottom' # one of 'top', 'bottom', 'top and bottom'
79-
80-
# Deny or allow anonymous access to the web interface
81-
ANONYMOUS_ACCESS = 'deny' # either 'deny' or 'allow'
82-
83-
# Deny or allow anonymous users to register through the web interface
84-
ANONYMOUS_REGISTER = 'deny' # either 'deny' or 'allow'
85-
86-
# Deny or allow anonymous users to register through the mail interface
87-
ANONYMOUS_REGISTER_MAIL = 'deny' # either 'deny' or 'allow'
88-
89-
# Send nosy messages to the author of the message
90-
MESSAGES_TO_AUTHOR = 'no' # either 'yes' or 'no'
91-
92-
# Does the author of a message get placed on the nosy list automatically?
93-
# If 'new' is used, then the author will only be added when a message
94-
# creates a new issue. If 'yes', then the author will be added on followups
95-
# too. If 'no', they're never added to the nosy.
96-
ADD_AUTHOR_TO_NOSY = 'new' # one of 'yes', 'no', 'new'
97-
98-
# Do the recipients (To:, Cc:) of a message get placed on the nosy list?
99-
# If 'new' is used, then the recipients will only be added when a message
100-
# creates a new issue. If 'yes', then the recipients will be added on
101-
# followups
102-
# too. If 'no', they're never added to the nosy.
103-
ADD_RECIPIENTS_TO_NOSY = 'new' # either 'yes', 'no', 'new'
190+
# roundup home is this package's directory
191+
INSTANCE_HOME=os.path.split(__file__)[0]
104192

105-
# Where to place the email signature
106-
EMAIL_SIGNATURE_POSITION = 'bottom' # one of 'top', 'bottom', 'none'
193+
# The SMTP mail host that roundup will use to send mail
194+
MAILHOST = 'localhost'
107195

108-
# Keep email citations
109-
EMAIL_KEEP_QUOTED_TEXT = 'no' # either 'yes' or 'no'
196+
# The domain name used for email addresses.
197+
MAIL_DOMAIN = 'your.tracker.email.domain.example'
110198

111-
# Preserve the email body as is
112-
EMAIL_LEAVE_BODY_UNCHANGED = 'no' # either 'yes' or 'no'
199+
# the next two are only used for the standalone HTTP server.
200+
HTTP_HOST = ''
201+
HTTP_PORT = 9080
113202

114-
# Default class to use in the mailgw if one isn't supplied in email
115-
# subjects. To disable, comment out the variable below or leave it blank.
116-
# Examples:
117-
MAIL_DEFAULT_CLASS = 'issue' # use "issue" class by default
118-
#MAIL_DEFAULT_CLASS = '' # disable (or just comment the var out)
203+
# This is the directory that the database is going to be stored in
204+
DATABASE = os.path.join(INSTANCE_HOME, 'db')
205+
206+
# This is the directory that the HTML templates reside in
207+
TEMPLATES = os.path.join(INSTANCE_HOME, 'html')
208+
209+
# A descriptive name for your roundup instance
210+
INSTANCE_NAME = 'Roundup issue tracker'
211+
212+
# The email address that mail to roundup should go to
213+
ISSUE_TRACKER_EMAIL = 'issue_tracker@%s'%MAIL_DOMAIN
214+
215+
# The web address that the instance is viewable at
216+
ISSUE_TRACKER_WEB = 'http://your.tracker.url.example/'
217+
218+
# The email address that roundup will complain to if it runs into trouble
219+
ADMIN_EMAIL = 'roundup-admin@%s'%MAIL_DOMAIN
220+
221+
# Somewhere for roundup to log stuff internally sent to stdout or stderr
222+
LOG = os.path.join(INSTANCE_HOME, 'roundup.log')
223+
224+
# Where to place the web filtering HTML on the index page
225+
FILTER_POSITION = 'bottom' # one of 'top', 'bottom', 'top and bottom'
226+
227+
# Deny or allow anonymous access to the web interface
228+
ANONYMOUS_ACCESS = 'deny' # either 'deny' or 'allow'
229+
230+
# Deny or allow anonymous users to register through the web interface
231+
ANONYMOUS_REGISTER = 'deny' # either 'deny' or 'allow'
232+
233+
# Deny or allow anonymous users to register through the mail interface
234+
ANONYMOUS_REGISTER_MAIL = 'deny' # either 'deny' or 'allow'
235+
236+
# Send nosy messages to the author of the message
237+
MESSAGES_TO_AUTHOR = 'no' # either 'yes' or 'no'
238+
239+
# Does the author of a message get placed on the nosy list automatically?
240+
# If 'new' is used, then the author will only be added when a message
241+
# creates a new issue. If 'yes', then the author will be added on followups
242+
# too. If 'no', they're never added to the nosy.
243+
ADD_AUTHOR_TO_NOSY = 'new' # one of 'yes', 'no', 'new'
244+
245+
# Do the recipients (To:, Cc:) of a message get placed on the nosy list?
246+
# If 'new' is used, then the recipients will only be added when a message
247+
# creates a new issue. If 'yes', then the recipients will be added on followups
248+
# too. If 'no', they're never added to the nosy.
249+
ADD_RECIPIENTS_TO_NOSY = 'new' # either 'yes', 'no', 'new'
250+
251+
# Where to place the email signature
252+
EMAIL_SIGNATURE_POSITION = 'bottom' # one of 'top', 'bottom', 'none'
253+
254+
# Keep email citations
255+
EMAIL_KEEP_QUOTED_TEXT = 'no' # either 'yes' or 'no'
256+
257+
# Preserve the email body as is
258+
EMAIL_LEAVE_BODY_UNCHANGED = 'no' # either 'yes' or 'no'
259+
260+
# Default class to use in the mailgw if one isn't supplied in email
261+
# subjects. To disable, comment out the variable below or leave it blank.
262+
# Examples:
263+
MAIL_DEFAULT_CLASS = 'issue' # use "issue" class by default
264+
#MAIL_DEFAULT_CLASS = '' # disable (or just comment the var out)
265+
266+
# Define what index links are available in the header, and what their
267+
# labels are. Each key is used to look up one of the index specifications
268+
# below - so 'DEFAULT' will use 'DEFAULT_INDEX'.
269+
# Where the FILTERSPEC has 'assignedto' with a value of None, it will be
270+
# replaced by the id of the logged-in user.
271+
HEADER_INDEX_LINKS = ['DEFAULT', 'UNASSIGNED', 'USER']
272+
273+
# list the classes that users are able to add nodes to
274+
HEADER_ADD_LINKS = ['issue']
275+
276+
# list the classes that users can search
277+
HEADER_SEARCH_LINKS = ['issue']
278+
279+
# list search filters per class
280+
SEARCH_FILTERS = ['ISSUE_FILTER', 'SUPPORT_FILTER']
281+
282+
# Now the DEFAULT display specification. TODO: describe format
283+
DEFAULT_INDEX = {
284+
'LABEL': 'All Issues',
285+
'CLASS': 'issue',
286+
'SORT': ['-activity'],
287+
'GROUP': ['priority'],
288+
'FILTER': ['status'],
289+
'COLUMNS': ['id','activity','title','creator','assignedto'],
290+
'FILTERSPEC': {
291+
'status': ['-1', '1', '2', '3', '4', '5', '6', '7'],
292+
},
293+
}
294+
295+
# The "unsassigned issues" index
296+
UNASSIGNED_INDEX = {
297+
'LABEL': 'Unassigned Issues',
298+
'CLASS': 'issue',
299+
'SORT': ['-activity'],
300+
'GROUP': ['priority'],
301+
'FILTER': ['status', 'assignedto'],
302+
'COLUMNS': ['id','activity','title','creator','status'],
303+
'FILTERSPEC': {
304+
'status': ['-1', '1', '2', '3', '4', '5', '6', '7'],
305+
'assignedto': ['-1'],
306+
},
307+
}
308+
309+
# The "my issues" index -- note that the user's id will replace the
310+
# 'CURRENT USER' value of the "assignedto" filterspec
311+
USER_INDEX = {
312+
'LABEL': 'My Issues',
313+
'CLASS': 'issue',
314+
'SORT': ['-activity'],
315+
'GROUP': ['priority'],
316+
'FILTER': ['status', 'assignedto'],
317+
'COLUMNS': ['id','activity','title','creator','status'],
318+
'FILTERSPEC': {
319+
'status': ['-1', '1', '2', '3', '4', '5', '6', '7'],
320+
'assignedto': 'CURRENT USER',
321+
},
322+
}
323+
324+
ISSUE_FILTER = {
325+
'CLASS': 'issue',
326+
'FILTER': ['status', 'priority', 'assignedto', 'creator']
327+
}
328+
329+
SUPPORT_FILTER = {
330+
'CLASS': 'issue',
331+
'FILTER': ['status', 'priority', 'assignedto', 'creator']
332+
}
119333

120334

121335
Instance Schema

0 commit comments

Comments
 (0)