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
1=== modified file '.bzrignore'
2--- .bzrignore 2009-07-14 12:13:25 +0000
3+++ .bzrignore 2009-07-19 05:37:47 +0000
4@@ -35,3 +35,4 @@
5
6 debug_data
7 _trial_temp
8+doc/api
9
10=== modified file 'GTG/core/requester.py'
11--- GTG/core/requester.py 2009-07-14 13:09:19 +0000
12+++ GTG/core/requester.py 2009-07-19 07:16:20 +0000
13@@ -18,24 +18,18 @@
14 # -----------------------------------------------------------------------------
15
16
17-#Requester is a pure View object. It will not do anything but it will
18-#be used by any Interface to handle the requests to the datastore
19-
20-#There could be multiple requester. It means that a requester should never
21-#Hold any data except a reference to its datastore.
22-
23-class Requester :
24+class Requester:
25 """A view on a GTG datastore.
26
27- `Requester` is a stateless object that simply provides a nice API for user
28- interfaces to use for datastore operations.
29+ L{Requester} is a stateless object that simply provides a nice API for
30+ user interfaces to use for datastore operations.
31
32- Multiple `Requester`s can exist on the same datastore, so they should
33+ Multiple L{Requester}s can exist on the same datastore, so they should
34 never have state of their own.
35 """
36
37 def __init__(self, datastore):
38- """Construct a `Requester`."""
39+ """Construct a L{Requester}."""
40 self.ds = datastore
41
42 def connect(self, signal, func):
43@@ -49,12 +43,12 @@
44 return self.ds.has_task(tid)
45
46 def get_task(self, tid):
47- """Get the task with the given 'tid'.
48-
49- If no such task exists, create it and force the tid to be 'tid'.
50-
51- :param tid: The task id.
52- :return: A task.
53+ """Get the task with the given C{tid}.
54+
55+ If no such task exists, create it and force the tid to be C{tid}.
56+
57+ @param tid: The task id.
58+ @return: A task.
59 """
60 task = self.ds.get_task(tid)
61 return task
62@@ -64,10 +58,10 @@
63
64 Note: this modifies the datastore.
65
66- :param pid: The project where the new task will be created.
67- :param tags: The tags for the new task. If not provided, then the
68+ @param pid: The project where the new task will be created.
69+ @param tags: The tags for the new task. If not provided, then the
70 task will have no tags.
71- :param newtask: 'True' if this is creating a task, 'False' if
72+ @param newtask: C{True} if this is creating a task, C{False} if
73 importing an existing task.
74 """
75 # XXX: The docs don't make it clear why you'd ever need to pass in
76@@ -83,7 +77,7 @@
77
78 Note: this modifies the datastore.
79
80- :param tid: The id of the task to be deleted.
81+ @param tid: The id of the task to be deleted.
82 """
83 self.ds.delete_task(tid)
84
85@@ -93,19 +87,19 @@
86
87 By default, returns a list of all the tids of all active tasks.
88
89- :param tags: A list of tags. If provided, restricts the list of
90+ @param tags: A list of tags. If provided, restricts the list of
91 returned tasks to those that have one or more of these tags.
92- :param status: A list of statuses. If provided, restricts the list of
93+ @param status: A list of statuses. If provided, restricts the list of
94 returned tasks to those that are in one of these states.
95- :param notag_only: If True, only include tasks without tags. Defaults
96- to False.
97- :param started_only: If True, only include tasks that have been
98+ @param notag_only: If True, only include tasks without tags. Defaults
99+ to C{False}.
100+ @param started_only: If True, only include tasks that have been
101 started. That is, tasks that have an already-passed start date or
102- tasks with no startdate. Defaults to 'True'.
103- :param is_root: If True, only include tasks that have no parent in the
104+ tasks with no startdate. Defaults to C{True}.
105+ @param is_root: If True, only include tasks that have no parent in the
106 current selection. Defaults to False.
107
108- :return: A list of task ids (tids).
109+ @return: A list of task ids (tids).
110 """
111 l_tasks = []
112 for tid in self.ds.all_tasks():
113@@ -152,12 +146,12 @@
114 workable=False):
115 """Return a list of task ids for all active tasks.
116
117- See `get_tasks_list` for more information about the parameters.
118+ See L{get_tasks_list} for more information about the parameters.
119
120- :param workable: If True, then only include tasks with no pending
121+ @param workable: If C{True}, then only include tasks with no pending
122 subtasks and that can be done directly and exclude any tasks that
123- have a 'nonworkview' tag which is not explicitly provided in the
124- 'tags' parameter. Defaults to False.
125+ have a C{nonworkview} tag which is not explicitly provided in the
126+ C{tags} parameter. Defaults to C{False}.
127 """
128 l_tasks = []
129 if workable:
130@@ -198,7 +192,7 @@
131
132 "Closed" means either "done", "dismissed" or "deleted".
133
134- See `get_tasks_list` for more information about the parameters.
135+ See L{get_tasks_list} for more information about the parameters.
136 """
137 closed = ["Done", "Dismiss", "Deleted"]
138 return self.get_tasks_list(
139@@ -224,8 +218,8 @@
140
141 Note: this modifies the datastore.
142
143- :param tagname: The name of the new tag.
144- :return: The newly-created tag.
145+ @param tagname: The name of the new tag.
146+ @return: The newly-created tag.
147 """
148 return self.ds.get_tagstore().new_tag(tagname)
149
150@@ -235,8 +229,8 @@
151 def get_all_tags(self):
152 """Return a list of every tag that was ever used."""
153 return list(self.ds.get_tagstore().get_all_tags())
154-
155- def get_notag_tag(self) :
156+
157+ def get_notag_tag(self):
158 return self.ds.get_tagstore().get_notag_tag()
159
160 def get_alltag_tag(self):
161@@ -245,7 +239,7 @@
162 def get_used_tags(self):
163 """Return tags currently used by a task.
164
165- :return: A list of tags used by a task.
166+ @return: A list of tags used by a task.
167 """
168 # FIXME: it should be only active and visible tasks.
169 l = []
170
171=== modified file 'GTG/core/tagstore.py'
172--- GTG/core/tagstore.py 2009-07-17 11:39:38 +0000
173+++ GTG/core/tagstore.py 2009-07-19 07:18:04 +0000
174@@ -150,22 +150,22 @@
175 ######################### Tag ###########################################
176
177 class Tag:
178- """A short name that can be applied to Tasks.
179+ """A short name that can be applied to L{Task}s.
180
181 I mean, surely you must know what a tag is by now. Think Gmail,
182 del.icio.us, Flickr et al.
183
184- A tag is defined by its name, which in most cases is '@something'. A tag
185+ A tag is defined by its name, which in most cases is C{@something}. A tag
186 can also have multiple arbitrary attributes. The only attribute enforced
187- for tags is 'name', which always matches `Tag.get_name()`.
188+ for tags is C{name}, which always matches L{Tag.get_name()}.
189 """
190
191 def __init__(self, name, save_cllbk=None):
192 """Construct a tag.
193
194- :param name: The name of the tag. Should be a string, generally a
195+ @param name: The name of the tag. Should be a string, generally a
196 short one.
197- :param save_cllbk: A nullary callable, called whenever an attribute
198+ @param save_cllbk: A nullary callable, called whenever an attribute
199 is set.
200 """
201 self._name = str(name)
202@@ -179,10 +179,10 @@
203 def set_attribute(self, att_name, att_value):
204 """Set an arbitrary attribute.
205
206- This will call the 'save_cllbk' callback passed to the constructor.
207+ This will call the C{save_cllbk} callback passed to the constructor.
208
209- :param att_name: The name of the attribute.
210- :param att_value: The value of the attribute. Will be converted to a
211+ @param att_name: The name of the attribute.
212+ @param att_value: The value of the attribute. Will be converted to a
213 string.
214 """
215 if att_name == "name":
216@@ -198,16 +198,16 @@
217 self._save()
218
219 def get_attribute(self, att_name):
220- """Get the attribute 'att_name'.
221+ """Get the attribute C{att_name}.
222
223- Returns None if there is no attribute matching 'att_name'.
224+ Returns C{None} if there is no attribute matching C{att_name}.
225 """
226 return self._attributes.get(att_name, None)
227
228 def get_all_attributes(self, butname=False):
229 """Return a list of all attribute names.
230
231- :param butname: If True, exclude 'name' from the list of attribute
232+ @param butname: If True, exclude C{name} from the list of attribute
233 names.
234 """
235 attributes = self._attributes.keys()
236
237=== modified file 'GTG/taskeditor/taskview.py'
238--- GTG/taskeditor/taskview.py 2009-07-13 09:20:43 +0000
239+++ GTG/taskeditor/taskview.py 2009-07-19 05:57:00 +0000
240@@ -395,9 +395,10 @@
241
242 #This function is called so frequently that we should optimize it more.
243 def modified(self,buff=None,full=False) : #pylint: disable-msg=W0613
244- """
245- This function is called when the buffer has been modified,
246- it reflects the changes by:
247+ """Called when the buffer has been modified.
248+
249+ It reflects the changes by:
250+
251 1. Applying the title style on the first line
252 2. Changing the name of the window if title change
253 """
254
255=== modified file 'HACKING'
256--- HACKING 2009-07-14 12:13:11 +0000
257+++ HACKING 2009-07-19 07:15:57 +0000
258@@ -122,3 +122,39 @@
259 6. Update ``AUTHORS`` if the patch author is not already in there.
260
261 7. Merge the branch into trunk, then commit!
262+
263+
264+Documentation
265+-------------
266+
267+We'd love it so much if you could improve the docstrings that you find in GTG.
268+
269+We use the docstring conventions outlined in PEP 8
270+<http://www.python.org/dev/peps/pep-0008/> and PEP 257
271+<http://www.python.org/dev/peps/pep-0257/>, except modified to support epytext
272+markup. Information on epytext markup can be found at
273+<http://epydoc.sourceforge.net/epytext.html>.
274+
275+You can generate the API docs by running::
276+
277+ make apidocs
278+
279+This builds the API documentation inside ``doc/api`` in your working tree. If
280+you are running GNOME, you can open it in your browser with::
281+
282+ gnome-open doc/api/index.html
283+
284+You can also run::
285+
286+ make edit-apidocs
287+
288+To launch a pydoctor server at http://localhost:8080/ that will let you edit
289+API documentation in place. The feature has a few rough edges, but can be
290+really useful for editing and extending API docs. To actually apply your edits
291+to the tree::
292+
293+ wget http://localhost:8080/rawBigDiff -q -O- | bzr patch
294+
295+Remember, docstrings should be written for people who don't know much about
296+the code. Focus on ''why'' things are the way they are, and on describing
297+''what'' they are in the first place.
298
299=== modified file 'Makefile'
300--- Makefile 2009-07-14 12:15:18 +0000
301+++ Makefile 2009-07-19 07:25:32 +0000
302@@ -7,6 +7,7 @@
303 clean:
304 rm -rf _trial_temp
305 rm -rf debug_data
306+ rm -rf doc/api
307 find . -name '*.pyc' -print0 | xargs -0 rm -f
308 find . -name '*~' -print0 | xargs -0 rm -f
309
310@@ -19,7 +20,20 @@
311 find . -name '*.py' -print0 | xargs -0 ./scripts/pep8.py
312 find . -name '*.py' -print0 | xargs -0 ./scripts/pep8.py --repeat | wc -l
313
314+# Build API documentation.
315+apidocs:
316+ pydoctor --add-package GTG --make-html --html-output=doc/api \
317+ --project-name=GTG --project-url=http://gtg.fritalk.com/ \
318+ -q -q --verbose-about=epydoc2stan2 --verbose-about=epydoc2stan2
319+
320+edit-apidocs:
321+ pydoctor --add-package GTG --make-html --html-output=doc/api \
322+ --project-name=GTG --project-url=http://gtg.fritalk.com/ \
323+ -q -q --verbose-about=epydoc2stan2 --verbose-about=epydoc2stan2 \
324+ --verbose-about=server --verbose-about=server --local-only \
325+ --server --edit
326+
327 # Check for coding standard violations & flakes.
328 lint: pyflakes pep8
329
330-.PHONY: check lint pyflakes pep8
331+.PHONY: check lint pyflakes pep8 apidocs
332
333=== modified file 'README'
334--- README 2009-07-14 13:02:39 +0000
335+++ README 2009-07-19 07:26:30 +0000
336@@ -1,11 +1,11 @@
337 ====== Getting Things GNOME! ======
338
339-Getting Things GNOME! (GTG) is a personal organizer for the GNOME desktop
340-environment inspired by the Getting Things Done (GTD) methodology. GTG is
341-designed with flexibility, adaptability, and ease of use in mind so it can be
342-used as more than just GTD software.
343+Getting Things GNOME! (GTG) is a personal organizer for the GNOME desktop
344+environment inspired by the Getting Things Done (GTD) methodology. GTG is
345+designed with flexibility, adaptability, and ease of use in mind so it can be
346+used as more than just GTD software.
347
348-GTG is intended to help you track everything you needto do and need to know,
349+GTG is intended to help you track everything you needto do and need to know,
350 from small tasks to large projects.
351
352 ===== Dependencies =====
353@@ -16,23 +16,28 @@
354 * python ConfigObj
355 * python gobject
356 * python XDG
357-Please refer to your system documentation for information on how to install
358+
359+To generate the API documentation, you'll also need to install 'pydoctor'.
360+
361+Please refer to your system documentation for information on how to install
362 these modules if they're not currently available.
363
364-To install these packages on Debian-based systems, execute the following
365+To install these packages on Debian-based systems, execute the following
366 command:
367 $ sudo aptitude install python-gtk2 python-glade2 python-xdg python-gobject\
368- python-configobj
369+ python-configobj python-pydoctor
370+
371+Note that the python-pydoctor package is broken in karmic.
372
373 ===== Installing and Running =====
374
375 To install GTG, either unpack the tarball:
376-
377+
378 $ tar xzvf gtg.tar.gz
379
380-or check out our bazaar branch for a development version (we try to keep those
381+or check out our bazaar branch for a development version (we try to keep those
382 unbroken and ready for production use):
383-
384+
385 $ bzr branch lp:gtg
386
387 To run GTG, either execute it directly from the source folder:
388@@ -59,7 +64,7 @@
389
390 ===== Quick add =====
391
392-In the quickadd line you can use "attribue:argument" with any title.
393+In the quickadd line you can use "attribute:argument" with any title.
394 Valid attributes are: "tags", "defer", "due"
395 E.g.:
396 "due:friday task description"

Subscribers

People subscribed via source and target branches

to status/vote changes: