annotate doc/implementation.txt @ 7371:a210f4437b49

Incomplete work to generate config doc from config.ini This is an incomplete attempt to allow generation of the config.ini documentation in reference.txt. It reformats the output of 'roundup_admin.py genconfig'. So it now includes all of the settings. Using a Makefile rule like: tracker_config.txt: ../roundup/configuration.py python3 ../roundup/scripts/roundup_admin.py \ genconfig _temp_config.txt sed -e '1,8d' \ -e 's/^\[\([a-z]*\)\]/\n.. index:: config.ini; sections \1\n\n.. code:: ini\n\n [\1]/' \ -e 's/^\([^[]\)/ \1/' \ _temp_config.txt > tracker_config.txt rm -f _temp_config.txt results in the config.ini split by section and index links being put in place. However some sections have a comment before the [section] marker. This comment is orphaned at the end of the prior section rather than starting the new section. A simple sed won't allow the lookahead needed to target the [section] marker and include the prior comment block. Also there are still have some long lines generated (> 65 characters). Maybe a python script can import configuration.py and output proper restructured text output? reference.txt: add a commented out include:: tracker_config.txt directive roundup/admin.py: don't require a tracker home for genconfig. So user can generate a clean config.ini on demand. Tracker home is still required for updateconfig. roundup/configuration.py: wrap lines better. A number of them are generating comments > 65 characters which is the targeted line length. This cleans up config.ini too, so is a good thing. website/www/conf.py: ignore doc/tracker_config.ini when processing.
author John Rouillard <rouilj@ieee.org>
date Wed, 17 May 2023 13:34:36 -0400
parents 81a634b7226e
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
7048
6f5054751fb6 Update meta description. Also fix test command in code.txt.
John Rouillard <rouilj@ieee.org>
parents: 6905
diff changeset
1 .. meta::
6f5054751fb6 Update meta description. Also fix test command in code.txt.
John Rouillard <rouilj@ieee.org>
parents: 6905
diff changeset
2 :description:
6f5054751fb6 Update meta description. Also fix test command in code.txt.
John Rouillard <rouilj@ieee.org>
parents: 6905
diff changeset
3 Additional implementation notes for the Roundup Issue Tracker.
7286
81a634b7226e Update description metadata
John Rouillard <rouilj@ieee.org>
parents: 7048
diff changeset
4 Supplement for docstrings in the Roundup package.
7048
6f5054751fb6 Update meta description. Also fix test command in code.txt.
John Rouillard <rouilj@ieee.org>
parents: 6905
diff changeset
5
688
b38f4f95bffd More doc tweaks
Richard Jones <richard@users.sourceforge.net>
parents: 686
diff changeset
6 ====================
111
6e8197a5880f Split off implementation notes into separate file in doc directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
7 Implementation notes
6e8197a5880f Split off implementation notes into separate file in doc directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
8 ====================
6e8197a5880f Split off implementation notes into separate file in doc directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
9
6e8197a5880f Split off implementation notes into separate file in doc directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
10 [see also the roundup package docstring]
6e8197a5880f Split off implementation notes into separate file in doc directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
11
6e8197a5880f Split off implementation notes into separate file in doc directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
12 There have been some modifications to the spec. I've marked these in the
6e8197a5880f Split off implementation notes into separate file in doc directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
13 source with 'XXX' comments when I remember to.
6e8197a5880f Split off implementation notes into separate file in doc directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
14
6e8197a5880f Split off implementation notes into separate file in doc directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
15 In short:
6e8197a5880f Split off implementation notes into separate file in doc directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
16 Class.find() - may match multiple properties, uses keyword args.
6e8197a5880f Split off implementation notes into separate file in doc directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
17
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1089
diff changeset
18 Class.filter() - isn't in the spec and it's very useful to have at the
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1089
diff changeset
19 Class level.
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1089
diff changeset
20
111
6e8197a5880f Split off implementation notes into separate file in doc directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
21 CGI interface index view specifier layout part - lose the '+' from the
6e8197a5880f Split off implementation notes into separate file in doc directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
22 sorting arguments (it's a reserved URL character ;). Just made no
6e8197a5880f Split off implementation notes into separate file in doc directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
23 prefix mean ascending and '-' prefix descending.
6e8197a5880f Split off implementation notes into separate file in doc directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
24
6e8197a5880f Split off implementation notes into separate file in doc directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
25 ItemClass - renamed to IssueClass to better match it only having one
6e8197a5880f Split off implementation notes into separate file in doc directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
26 hypderdb class "issue". Allowing > 1 hyperdb class breaks the
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1089
diff changeset
27 "superseder" multilink (since it can only link to one thing, and
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1089
diff changeset
28 we'd want bugs to link to support and vice-versa).
111
6e8197a5880f Split off implementation notes into separate file in doc directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
29
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1089
diff changeset
30 template - the call="link()" is handled by special-case mechanisms in
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1089
diff changeset
31 my top-level CGI handler. In a nutshell, the handler looks for a
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1089
diff changeset
32 method on itself called 'index%s' or 'item%s' where %s is a class.
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1089
diff changeset
33 Most items pass on to the templating mechanism, but the file class
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1089
diff changeset
34 _always_ does downloading. It'll probably stay this way too...
111
6e8197a5880f Split off implementation notes into separate file in doc directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
35
1089
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
36 template - call="link(property)" may be used to link "the current item"
111
6e8197a5880f Split off implementation notes into separate file in doc directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
37 (from an index) - the link text is the property specified.
6e8197a5880f Split off implementation notes into separate file in doc directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
38
6e8197a5880f Split off implementation notes into separate file in doc directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
39 template - added functions that I found very useful: List, History and
6e8197a5880f Split off implementation notes into separate file in doc directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
40 Submit.
6e8197a5880f Split off implementation notes into separate file in doc directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
41
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1089
diff changeset
42 template - items must specify the message lists, history, etc. Having
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1089
diff changeset
43 them by default was sometimes not wanted.
111
6e8197a5880f Split off implementation notes into separate file in doc directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
44
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1089
diff changeset
45 template - index view determines its default columns from the
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1089
diff changeset
46 template's ``tal:condition="request/show/<property>"`` directives.
111
6e8197a5880f Split off implementation notes into separate file in doc directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
47
6e8197a5880f Split off implementation notes into separate file in doc directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
48 template - menu() and field() look awfully similar now .... ;)
6e8197a5880f Split off implementation notes into separate file in doc directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
49
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents: 688
diff changeset
50 roundup_admin.py - the command-line tool has a lot more commands at its
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents: 688
diff changeset
51 disposal
111
6e8197a5880f Split off implementation notes into separate file in doc directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
52
686
c52122f38c9b Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents: 111
diff changeset
53 -----------------
c52122f38c9b Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents: 111
diff changeset
54
c52122f38c9b Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents: 111
diff changeset
55 Back to `Table of Contents`_
c52122f38c9b Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents: 111
diff changeset
56
6905
9ca128103a3a fix broken links to doc table of contents
John Rouillard <rouilj@ieee.org>
parents: 4557
diff changeset
57 .. _`Table of Contents`: ../docs.html
686
c52122f38c9b Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents: 111
diff changeset
58

Roundup Issue Tracker: http://roundup-tracker.org/