GTG

Merge lp:~jml/gtg/doc-generation into lp:~gtg/gtg/old-trunk

  1. doc-generation
  2. Merge into old-trunk
Proposed by Jonathan Lange
Status: Merged
Merged at revision: not available
Proposed branch: lp:~jml/gtg/doc-generation
Merge into: lp:~gtg/gtg/old-trunk
Diff against target: None lines
To merge this branch: bzr merge lp:~jml/gtg/doc-generation
Reviewer Review Type Date Requested Status
Bertrand Rousseau (community) Approve
Review via email: mp+9020@code.launchpad.net
To post a comment you must log in.
Revision history for this message
Jonathan Lange (jml) wrote :

This branch adds 'make apidocs' and 'make edit-apidocs' targets to the Makefile and updates the HACKING file to explain how docstrings & API docs should work. I've also updated the README file to indicate the new optional dependencies.

To build the docs, you'll need pydoctor & its dependencies. pydoctor is best retrieved from lp:pydoctor. If you can't figure out how to get it running from the README & HACKING docs, then the documentation needs to be improved.

The rest of the branch is fixes to docstrings that we found when I tried to generate the docs.

An example build of the API docs can be found at http://static.mumak.net/gtg-api/.

Revision history for this message
Bertrand Rousseau (bertrand-rousseau) :
review: Approve

Preview Diff

[H/L] Next/Prev Comment, [J/K] Next/Prev File, [N/P] Next/Prev Hunk
=== modified file '.bzrignore'
--- .bzrignore 2009-07-14 12:13:25 +0000
+++ .bzrignore 2009-07-19 05:37:47 +0000
@@ -35,3 +35,4 @@
3535
36debug_data36debug_data
37_trial_temp37_trial_temp
38doc/api
3839
=== modified file 'GTG/core/requester.py'
--- GTG/core/requester.py 2009-07-14 13:09:19 +0000
+++ GTG/core/requester.py 2009-07-19 07:16:20 +0000
@@ -18,24 +18,18 @@
18# -----------------------------------------------------------------------------18# -----------------------------------------------------------------------------
1919
2020
21#Requester is a pure View object. It will not do anything but it will21class Requester:
22#be used by any Interface to handle the requests to the datastore
23
24#There could be multiple requester. It means that a requester should never
25#Hold any data except a reference to its datastore.
26
27class Requester :
28 """A view on a GTG datastore.22 """A view on a GTG datastore.
2923
30 `Requester` is a stateless object that simply provides a nice API for user24 L{Requester} is a stateless object that simply provides a nice API for
31 interfaces to use for datastore operations.25 user interfaces to use for datastore operations.
3226
33 Multiple `Requester`s can exist on the same datastore, so they should27 Multiple L{Requester}s can exist on the same datastore, so they should
34 never have state of their own.28 never have state of their own.
35 """29 """
3630
37 def __init__(self, datastore):31 def __init__(self, datastore):
38 """Construct a `Requester`."""32 """Construct a L{Requester}."""
39 self.ds = datastore33 self.ds = datastore
4034
41 def connect(self, signal, func):35 def connect(self, signal, func):
@@ -49,12 +43,12 @@
49 return self.ds.has_task(tid)43 return self.ds.has_task(tid)
5044
51 def get_task(self, tid):45 def get_task(self, tid):
52 """Get the task with the given 'tid'.46 """Get the task with the given C{tid}.
5347
54 If no such task exists, create it and force the tid to be 'tid'.48 If no such task exists, create it and force the tid to be C{tid}.
5549
56 :param tid: The task id.50 @param tid: The task id.
57 :return: A task.51 @return: A task.
58 """52 """
59 task = self.ds.get_task(tid)53 task = self.ds.get_task(tid)
60 return task54 return task
@@ -64,10 +58,10 @@
6458
65 Note: this modifies the datastore.59 Note: this modifies the datastore.
6660
67 :param pid: The project where the new task will be created.61 @param pid: The project where the new task will be created.
68 :param tags: The tags for the new task. If not provided, then the62 @param tags: The tags for the new task. If not provided, then the
69 task will have no tags.63 task will have no tags.
70 :param newtask: 'True' if this is creating a task, 'False' if64 @param newtask: C{True} if this is creating a task, C{False} if
71 importing an existing task.65 importing an existing task.
72 """66 """
73 # XXX: The docs don't make it clear why you'd ever need to pass in67 # XXX: The docs don't make it clear why you'd ever need to pass in
@@ -83,7 +77,7 @@
8377
84 Note: this modifies the datastore.78 Note: this modifies the datastore.
8579
86 :param tid: The id of the task to be deleted.80 @param tid: The id of the task to be deleted.
87 """81 """
88 self.ds.delete_task(tid)82 self.ds.delete_task(tid)
8983
@@ -93,19 +87,19 @@
9387
94 By default, returns a list of all the tids of all active tasks.88 By default, returns a list of all the tids of all active tasks.
9589
96 :param tags: A list of tags. If provided, restricts the list of90 @param tags: A list of tags. If provided, restricts the list of
97 returned tasks to those that have one or more of these tags.91 returned tasks to those that have one or more of these tags.
98 :param status: A list of statuses. If provided, restricts the list of92 @param status: A list of statuses. If provided, restricts the list of
99 returned tasks to those that are in one of these states.93 returned tasks to those that are in one of these states.
100 :param notag_only: If True, only include tasks without tags. Defaults94 @param notag_only: If True, only include tasks without tags. Defaults
101 to False.95 to C{False}.
102 :param started_only: If True, only include tasks that have been96 @param started_only: If True, only include tasks that have been
103 started. That is, tasks that have an already-passed start date or97 started. That is, tasks that have an already-passed start date or
104 tasks with no startdate. Defaults to 'True'.98 tasks with no startdate. Defaults to C{True}.
105 :param is_root: If True, only include tasks that have no parent in the99 @param is_root: If True, only include tasks that have no parent in the
106 current selection. Defaults to False.100 current selection. Defaults to False.
107101
108 :return: A list of task ids (tids).102 @return: A list of task ids (tids).
109 """103 """
110 l_tasks = []104 l_tasks = []
111 for tid in self.ds.all_tasks():105 for tid in self.ds.all_tasks():
@@ -152,12 +146,12 @@
152 workable=False):146 workable=False):
153 """Return a list of task ids for all active tasks.147 """Return a list of task ids for all active tasks.
154148
155 See `get_tasks_list` for more information about the parameters.149 See L{get_tasks_list} for more information about the parameters.
156150
157 :param workable: If True, then only include tasks with no pending151 @param workable: If C{True}, then only include tasks with no pending
158 subtasks and that can be done directly and exclude any tasks that152 subtasks and that can be done directly and exclude any tasks that
159 have a 'nonworkview' tag which is not explicitly provided in the153 have a C{nonworkview} tag which is not explicitly provided in the
160 'tags' parameter. Defaults to False.154 C{tags} parameter. Defaults to C{False}.
161 """155 """
162 l_tasks = []156 l_tasks = []
163 if workable:157 if workable:
@@ -198,7 +192,7 @@
198192
199 "Closed" means either "done", "dismissed" or "deleted".193 "Closed" means either "done", "dismissed" or "deleted".
200194
201 See `get_tasks_list` for more information about the parameters.195 See L{get_tasks_list} for more information about the parameters.
202 """196 """
203 closed = ["Done", "Dismiss", "Deleted"]197 closed = ["Done", "Dismiss", "Deleted"]
204 return self.get_tasks_list(198 return self.get_tasks_list(
@@ -224,8 +218,8 @@
224218
225 Note: this modifies the datastore.219 Note: this modifies the datastore.
226220
227 :param tagname: The name of the new tag.221 @param tagname: The name of the new tag.
228 :return: The newly-created tag.222 @return: The newly-created tag.
229 """223 """
230 return self.ds.get_tagstore().new_tag(tagname)224 return self.ds.get_tagstore().new_tag(tagname)
231225
@@ -235,8 +229,8 @@
235 def get_all_tags(self):229 def get_all_tags(self):
236 """Return a list of every tag that was ever used."""230 """Return a list of every tag that was ever used."""
237 return list(self.ds.get_tagstore().get_all_tags())231 return list(self.ds.get_tagstore().get_all_tags())
238 232
239 def get_notag_tag(self) :233 def get_notag_tag(self):
240 return self.ds.get_tagstore().get_notag_tag()234 return self.ds.get_tagstore().get_notag_tag()
241235
242 def get_alltag_tag(self):236 def get_alltag_tag(self):
@@ -245,7 +239,7 @@
245 def get_used_tags(self):239 def get_used_tags(self):
246 """Return tags currently used by a task.240 """Return tags currently used by a task.
247241
248 :return: A list of tags used by a task.242 @return: A list of tags used by a task.
249 """243 """
250 # FIXME: it should be only active and visible tasks.244 # FIXME: it should be only active and visible tasks.
251 l = []245 l = []
252246
=== modified file 'GTG/core/tagstore.py'
--- GTG/core/tagstore.py 2009-07-17 11:39:38 +0000
+++ GTG/core/tagstore.py 2009-07-19 07:18:04 +0000
@@ -150,22 +150,22 @@
150######################### Tag ###########################################150######################### Tag ###########################################
151151
152class Tag:152class Tag:
153 """A short name that can be applied to Tasks.153 """A short name that can be applied to L{Task}s.
154154
155 I mean, surely you must know what a tag is by now. Think Gmail,155 I mean, surely you must know what a tag is by now. Think Gmail,
156 del.icio.us, Flickr et al.156 del.icio.us, Flickr et al.
157157
158 A tag is defined by its name, which in most cases is '@something'. A tag158 A tag is defined by its name, which in most cases is C{@something}. A tag
159 can also have multiple arbitrary attributes. The only attribute enforced159 can also have multiple arbitrary attributes. The only attribute enforced
160 for tags is 'name', which always matches `Tag.get_name()`.160 for tags is C{name}, which always matches L{Tag.get_name()}.
161 """161 """
162162
163 def __init__(self, name, save_cllbk=None):163 def __init__(self, name, save_cllbk=None):
164 """Construct a tag.164 """Construct a tag.
165165
166 :param name: The name of the tag. Should be a string, generally a166 @param name: The name of the tag. Should be a string, generally a
167 short one.167 short one.
168 :param save_cllbk: A nullary callable, called whenever an attribute168 @param save_cllbk: A nullary callable, called whenever an attribute
169 is set.169 is set.
170 """170 """
171 self._name = str(name)171 self._name = str(name)
@@ -179,10 +179,10 @@
179 def set_attribute(self, att_name, att_value):179 def set_attribute(self, att_name, att_value):
180 """Set an arbitrary attribute.180 """Set an arbitrary attribute.
181181
182 This will call the 'save_cllbk' callback passed to the constructor.182 This will call the C{save_cllbk} callback passed to the constructor.
183183
184 :param att_name: The name of the attribute.184 @param att_name: The name of the attribute.
185 :param att_value: The value of the attribute. Will be converted to a185 @param att_value: The value of the attribute. Will be converted to a
186 string.186 string.
187 """187 """
188 if att_name == "name":188 if att_name == "name":
@@ -198,16 +198,16 @@
198 self._save()198 self._save()
199199
200 def get_attribute(self, att_name):200 def get_attribute(self, att_name):
201 """Get the attribute 'att_name'.201 """Get the attribute C{att_name}.
202202
203 Returns None if there is no attribute matching 'att_name'.203 Returns C{None} if there is no attribute matching C{att_name}.
204 """204 """
205 return self._attributes.get(att_name, None)205 return self._attributes.get(att_name, None)
206206
207 def get_all_attributes(self, butname=False):207 def get_all_attributes(self, butname=False):
208 """Return a list of all attribute names.208 """Return a list of all attribute names.
209209
210 :param butname: If True, exclude 'name' from the list of attribute210 @param butname: If True, exclude C{name} from the list of attribute
211 names.211 names.
212 """212 """
213 attributes = self._attributes.keys()213 attributes = self._attributes.keys()
214214
=== modified file 'GTG/taskeditor/taskview.py'
--- GTG/taskeditor/taskview.py 2009-07-13 09:20:43 +0000
+++ GTG/taskeditor/taskview.py 2009-07-19 05:57:00 +0000
@@ -395,9 +395,10 @@
395 395
396 #This function is called so frequently that we should optimize it more. 396 #This function is called so frequently that we should optimize it more.
397 def modified(self,buff=None,full=False) : #pylint: disable-msg=W0613397 def modified(self,buff=None,full=False) : #pylint: disable-msg=W0613
398 """398 """Called when the buffer has been modified.
399 This function is called when the buffer has been modified,399
400 it reflects the changes by:400 It reflects the changes by:
401
401 1. Applying the title style on the first line402 1. Applying the title style on the first line
402 2. Changing the name of the window if title change403 2. Changing the name of the window if title change
403 """404 """
404405
=== modified file 'HACKING'
--- HACKING 2009-07-14 12:13:11 +0000
+++ HACKING 2009-07-19 07:15:57 +0000
@@ -122,3 +122,39 @@
122 6. Update ``AUTHORS`` if the patch author is not already in there.122 6. Update ``AUTHORS`` if the patch author is not already in there.
123123
124 7. Merge the branch into trunk, then commit!124 7. Merge the branch into trunk, then commit!
125
126
127Documentation
128-------------
129
130We'd love it so much if you could improve the docstrings that you find in GTG.
131
132We use the docstring conventions outlined in PEP 8
133<http://www.python.org/dev/peps/pep-0008/> and PEP 257
134<http://www.python.org/dev/peps/pep-0257/>, except modified to support epytext
135markup. Information on epytext markup can be found at
136<http://epydoc.sourceforge.net/epytext.html>.
137
138You can generate the API docs by running::
139
140 make apidocs
141
142This builds the API documentation inside ``doc/api`` in your working tree. If
143you are running GNOME, you can open it in your browser with::
144
145 gnome-open doc/api/index.html
146
147You can also run::
148
149 make edit-apidocs
150
151To launch a pydoctor server at http://localhost:8080/ that will let you edit
152API documentation in place. The feature has a few rough edges, but can be
153really useful for editing and extending API docs. To actually apply your edits
154to the tree::
155
156 wget http://localhost:8080/rawBigDiff -q -O- | bzr patch
157
158Remember, docstrings should be written for people who don't know much about
159the code. Focus on ''why'' things are the way they are, and on describing
160''what'' they are in the first place.
125161
=== modified file 'Makefile'
--- Makefile 2009-07-14 12:15:18 +0000
+++ Makefile 2009-07-19 07:25:32 +0000
@@ -7,6 +7,7 @@
7clean:7clean:
8 rm -rf _trial_temp8 rm -rf _trial_temp
9 rm -rf debug_data9 rm -rf debug_data
10 rm -rf doc/api
10 find . -name '*.pyc' -print0 | xargs -0 rm -f11 find . -name '*.pyc' -print0 | xargs -0 rm -f
11 find . -name '*~' -print0 | xargs -0 rm -f12 find . -name '*~' -print0 | xargs -0 rm -f
1213
@@ -19,7 +20,20 @@
19 find . -name '*.py' -print0 | xargs -0 ./scripts/pep8.py20 find . -name '*.py' -print0 | xargs -0 ./scripts/pep8.py
20 find . -name '*.py' -print0 | xargs -0 ./scripts/pep8.py --repeat | wc -l21 find . -name '*.py' -print0 | xargs -0 ./scripts/pep8.py --repeat | wc -l
2122
23# Build API documentation.
24apidocs:
25 pydoctor --add-package GTG --make-html --html-output=doc/api \
26 --project-name=GTG --project-url=http://gtg.fritalk.com/ \
27 -q -q --verbose-about=epydoc2stan2 --verbose-about=epydoc2stan2
28
29edit-apidocs:
30 pydoctor --add-package GTG --make-html --html-output=doc/api \
31 --project-name=GTG --project-url=http://gtg.fritalk.com/ \
32 -q -q --verbose-about=epydoc2stan2 --verbose-about=epydoc2stan2 \
33 --verbose-about=server --verbose-about=server --local-only \
34 --server --edit
35
22# Check for coding standard violations & flakes.36# Check for coding standard violations & flakes.
23lint: pyflakes pep837lint: pyflakes pep8
2438
25.PHONY: check lint pyflakes pep839.PHONY: check lint pyflakes pep8 apidocs
2640
=== modified file 'README'
--- README 2009-07-14 13:02:39 +0000
+++ README 2009-07-19 07:26:30 +0000
@@ -1,11 +1,11 @@
1====== Getting Things GNOME! ======1====== Getting Things GNOME! ======
22
3Getting Things GNOME! (GTG) is a personal organizer for the GNOME desktop 3Getting Things GNOME! (GTG) is a personal organizer for the GNOME desktop
4environment inspired by the Getting Things Done (GTD) methodology. GTG is 4environment inspired by the Getting Things Done (GTD) methodology. GTG is
5designed with flexibility, adaptability, and ease of use in mind so it can be 5designed with flexibility, adaptability, and ease of use in mind so it can be
6used as more than just GTD software. 6used as more than just GTD software.
77
8GTG is intended to help you track everything you needto do and need to know, 8GTG is intended to help you track everything you needto do and need to know,
9from small tasks to large projects.9from small tasks to large projects.
1010
11===== Dependencies =====11===== Dependencies =====
@@ -16,23 +16,28 @@
16 * python ConfigObj16 * python ConfigObj
17 * python gobject17 * python gobject
18 * python XDG18 * python XDG
19Please refer to your system documentation for information on how to install 19
20To generate the API documentation, you'll also need to install 'pydoctor'.
21
22Please refer to your system documentation for information on how to install
20these modules if they're not currently available.23these modules if they're not currently available.
2124
22To install these packages on Debian-based systems, execute the following 25To install these packages on Debian-based systems, execute the following
23command:26command:
24 $ sudo aptitude install python-gtk2 python-glade2 python-xdg python-gobject\27 $ sudo aptitude install python-gtk2 python-glade2 python-xdg python-gobject\
25 python-configobj28 python-configobj python-pydoctor
29
30Note that the python-pydoctor package is broken in karmic.
2631
27===== Installing and Running =====32===== Installing and Running =====
2833
29To install GTG, either unpack the tarball:34To install GTG, either unpack the tarball:
30 35
31 $ tar xzvf gtg.tar.gz36 $ tar xzvf gtg.tar.gz
3237
33or check out our bazaar branch for a development version (we try to keep those 38or check out our bazaar branch for a development version (we try to keep those
34unbroken and ready for production use):39unbroken and ready for production use):
35 40
36 $ bzr branch lp:gtg41 $ bzr branch lp:gtg
3742
38To run GTG, either execute it directly from the source folder:43To run GTG, either execute it directly from the source folder:
@@ -59,7 +64,7 @@
5964
60===== Quick add =====65===== Quick add =====
6166
62In the quickadd line you can use "attribue:argument" with any title. 67In the quickadd line you can use "attribute:argument" with any title.
63Valid attributes are: "tags", "defer", "due"68Valid attributes are: "tags", "defer", "due"
64E.g.:69E.g.:
65 "due:friday task description"70 "due:friday task description"

Subscribers

People subscribed via source and target branches

to status/vote changes: