[Sugar-devel] Patch for documentation of graphics/animator.py
Hello all,
I've made some changes to the docstrings in graphics/animator.py for its
documentation and have uploaded the HTML generated using sphinx at:
http://seeta.in/sugar/api/documentation/desttemp/html2/animator.html
You can compare it with the initial one at:
http://api.sugarlabs.org/sphinx/animator.html
Attaching the original and new animator.py files along with the patch
generated using 'git format-patch master'
I've also made a spreadsheet for the documentation and am maintaining it at
https://spreadsheets.google.com/a/seeta.in/ccc?key=0AjslliQkdNyvdFZjWnNwcEZzSC1fMkt6ZDlOOUFFMUE&hl=en#gid=0
Attaching it.
Please see if you would like to help or let me know in case of any
suggestions/feedback.
Regards,
Kandarp.
API documentation-animator_py-1.xls
Description: MS-Excel spreadsheet
animator(original).py
Description: Binary data
# Copyright (C) 2007, Red Hat, Inc.
#
# This library is free software; you can redistribute it and/or
# modify it under the terms of the GNU Lesser General Public
# License as published by the Free Software Foundation; either
# version 2 of the License, or (at your option) any later version.
#
# This library is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
# Lesser General Public License for more details.
#
# You should have received a copy of the GNU Lesser General Public
# License along with this library; if not, write to the
# Free Software Foundation, Inc., 59 Temple Place - Suite 330,
# Boston, MA 02111-1307, USA.
"""
STABLE.
"""
import time
import gobject
EASE_OUT_EXPO = 0
EASE_IN_EXPO = 1
class Animator(gobject.GObject):
"""
:Inherits: gobject.GObject
"""
__gsignals__ = {
'completed': (gobject.SIGNAL_RUN_FIRST, gobject.TYPE_NONE, ([])),
}
def __init__(self, duration, fps=20, easing=EASE_OUT_EXPO):
gobject.GObject.__init__(self)
self._animations = []
self._duration = duration
self._interval = 1.0 / fps
self._easing = easing
self._timeout_sid = 0
self._start_time = None
def add(self, animation):
"""
Parameter
- animation:
Returns
- None
Description: Adds animation type
"""
self._animations.append(animation)
def remove_all(self):
"""
Parameters
- None
Returns
- None
Description: Stops animation, removes animation type
"""
self.stop()
self._animations = []
def start(self):
"""
Parameters
- None
Returns
- None
Description: Records starting time, sets timeout_sid
"""
if self._timeout_sid:
self.stop()
self._start_time = time.time()
self._timeout_sid = gobject.timeout_add(
int(self._interval * 1000), self._next_frame_cb)
def stop(self):
"""
Parameters
- None
Returns
- None
Description: Resets timeout_sid
"""
if self._timeout_sid:
gobject.source_remove(self._timeout_sid)
self._timeout_sid = 0
self.emit('completed')
def _next_frame_cb(self):
current_time = min(self._duration, time.time() - self._start_time)
current_time = max(current_time, 0.0)
for animation in self._animations:
animation.do_frame(current_time, self._duration, self._easing)
if current_time == self._duration:
self.stop()
return False
else:
return True
class Animation(object):
"""
:Inherits: object
"""
def __init__(self, start, end):
self.start = start
self.end = end
def do_frame(self, t, duration, easing):
"""
Parameters
- t:
- duration:
- easing:
Returns
- None
Description: Updates frame, ends after t=duration
"""
start = self.start
change = self.end - self.start
if t == duration:
# last frame
frame = self.end
else:
if easing == EASE_OUT_EXPO:
frame = change * (-pow(2, -10 * t / duration) + 1) + start
elif easing == EASE_IN_EXPO:
frame = change * pow(2, 10 * (t / duration - 1)) + start
self.next_frame(frame)
def next_frame(self, frame):
"""
Parameters
- frame:
Returns
- None
Description: pass, do nothing
"""
pass>From 596cf624f3babcbdc3ae666ad393834a3c0fb19f Mon Sep 17 00:00:00 2001
From: Kandarp Kaushik
Date: Thu, 12 Aug 2010 23:17:31 +0530
Subject: [PATCH] description of animator.py
---
animator1.py | 69
Re: [Sugar-devel] Patch for documentation of graphics/animator.py
On Sat, Aug 14, 2010 at 18:02, wrote: > Hello all, > > I've made some changes to the docstrings in graphics/animator.py for its > documentation and have uploaded the HTML generated using sphinx at: > http://seeta.in/sugar/api/documentation/desttemp/html2/animator.html > > You can compare it with the initial one at: > http://api.sugarlabs.org/sphinx/animator.html > > Attaching the original and new animator.py files along with the patch > generated using 'git format-patch master' > > I've also made a spreadsheet for the documentation and am maintaining it at > https://spreadsheets.google.com/a/seeta.in/ccc?key=0AjslliQkdNyvdFZjWnNwcEZzSC1fMkt6ZDlOOUFFMUE&hl=en#gid=0 > Attaching it. > > Please see if you would like to help or let me know in case of any > suggestions/feedback. Hi Kandarp, some suggestions follow: > Subject: [PATCH] description of animator.py The docstring for the module animator.py isn't really included in this patch. > animator1.py | 69 ++--- This is very weird as there's no animator1.py file in sugar-toolkit. Please go through a git tutorial first, we'll all save time. > +:Inherits: gobject.GObject Sphinx cannot get this information from the code? Is it common practice in sphinx-generated docs? > +Returns > +- None Can we leave this implicit? > +Description: Adds animation type Why type? Seems to be adding an Animation instance. > +Parameters > +- None Can we leave this implicit? > +Description: Stops animation, removes animation type See above. > +Description: Records starting time, sets timeout_sid Docstrings should describe functionality, not explain the implementation. > +class Animation(object): Watch out adding trailing spaces > +Description: Updates frame, ends after t=duration PEP 257 says to use the first line for the one-line summary. Are you using any documented guidelines for the format of the docstrings? I would _strongly_ advise to start by adding docstrings to packages and modules. And only once that's done then get to classes and other top-level elements, then finally to methods. If you try to document the details before understanding the big picture, you are likely to fail. Regards, Tomeu > Regards, > Kandarp. > > > ___ > Sugar-devel mailing list > Sugar-devel@lists.sugarlabs.org > http://lists.sugarlabs.org/listinfo/sugar-devel > > ___ Sugar-devel mailing list Sugar-devel@lists.sugarlabs.org http://lists.sugarlabs.org/listinfo/sugar-devel
Re: [Sugar-devel] Patch for documentation of graphics/animator.py
Tomeu, Thank you for the pointers. Appreciate it. We'll have a meeting this evening to discuss on your timely feedback. Regards, Manu On Sun, Aug 15, 2010 at 7:51 PM, Tomeu Vizoso wrote: > On Sat, Aug 14, 2010 at 18:02, wrote: > > Hello all, > > > > I've made some changes to the docstrings in graphics/animator.py for its > > documentation and have uploaded the HTML generated using sphinx at: > > http://seeta.in/sugar/api/documentation/desttemp/html2/animator.html > > > > You can compare it with the initial one at: > > http://api.sugarlabs.org/sphinx/animator.html > > > > Attaching the original and new animator.py files along with the patch > > generated using 'git format-patch master' > > > > I've also made a spreadsheet for the documentation and am maintaining it > at > > > https://spreadsheets.google.com/a/seeta.in/ccc?key=0AjslliQkdNyvdFZjWnNwcEZzSC1fMkt6ZDlOOUFFMUE&hl=en#gid=0 > > Attaching it. > > > > Please see if you would like to help or let me know in case of any > > suggestions/feedback. > > Hi Kandarp, some suggestions follow: > > > Subject: [PATCH] description of animator.py > > The docstring for the module animator.py isn't really included in this > patch. > > > animator1.py | 69 > ++--- > > This is very weird as there's no animator1.py file in sugar-toolkit. > Please go through a git tutorial first, we'll all save time. > > > +:Inherits: gobject.GObject > > Sphinx cannot get this information from the code? Is it common > practice in sphinx-generated docs? > > > +Returns > > +- None > > Can we leave this implicit? > > > +Description: Adds animation type > > Why type? Seems to be adding an Animation instance. > > > +Parameters > > +- None > > Can we leave this implicit? > > > +Description: Stops animation, removes animation type > > See above. > > > +Description: Records starting time, sets timeout_sid > > Docstrings should describe functionality, not explain the implementation. > > > +class Animation(object): > > Watch out adding trailing spaces > > > +Description: Updates frame, ends after t=duration > > PEP 257 says to use the first line for the one-line summary. > > Are you using any documented guidelines for the format of the docstrings? > > I would _strongly_ advise to start by adding docstrings to packages > and modules. And only once that's done then get to classes and other > top-level elements, then finally to methods. > > If you try to document the details before understanding the big > picture, you are likely to fail. > > Regards, > > Tomeu > > > Regards, > > Kandarp. > > > > > > ___ > > Sugar-devel mailing list > > Sugar-devel@lists.sugarlabs.org > > http://lists.sugarlabs.org/listinfo/sugar-devel > > > > > ___ Sugar-devel mailing list Sugar-devel@lists.sugarlabs.org http://lists.sugarlabs.org/listinfo/sugar-devel
Re: [Sugar-devel] Patch for documentation of graphics/animator.py
Tomeu, Thank you for the pointers. As recommended, we developed the devtutor activity, and uploaded its source code at http://git.sugarlabs.org/projects/devtutor. This is an activity to help understand the Sugar APIs for the developers. We did get a strong insight on key areas of activity development while working on this activity. We also revised the patch based on your feedback and recommendations. Thank you for your time. We are using PEP 257 as the documentation standard. Please have a look at the revised patch, and let us know your feedback - http://seeta.in/dextrose/API%20patch/. Hope it meets the requisite standards. If not, we'll be happy to revise it. As discussed with you on IRC, our next step is to add documentation of modules like sugar.graphics. Regards, Kandarp On Sun, Aug 15, 2010 at 7:51 PM, Tomeu Vizoso wrote: > On Sat, Aug 14, 2010 at 18:02, wrote: > > Hello all, > > > > I've made some changes to the docstrings in graphics/animator.py for its > > documentation and have uploaded the HTML generated using sphinx at: > > http://seeta.in/sugar/api/documentation/desttemp/html2/animator.html > > > > You can compare it with the initial one at: > > http://api.sugarlabs.org/sphinx/animator.html > > > > Attaching the original and new animator.py files along with the patch > > generated using 'git format-patch master' > > > > I've also made a spreadsheet for the documentation and am maintaining it > at > > > https://spreadsheets.google.com/a/seeta.in/ccc?key=0AjslliQkdNyvdFZjWnNwcEZzSC1fMkt6ZDlOOUFFMUE&hl=en#gid=0 > > Attaching it. > > > > Please see if you would like to help or let me know in case of any > > suggestions/feedback. > > Hi Kandarp, some suggestions follow: > > > Subject: [PATCH] description of animator.py > > The docstring for the module animator.py isn't really included in this > patch. > > > animator1.py | 69 > ++--- > > This is very weird as there's no animator1.py file in sugar-toolkit. > Please go through a git tutorial first, we'll all save time. > > > +:Inherits: gobject.GObject > > Sphinx cannot get this information from the code? Is it common > practice in sphinx-generated docs? > > > +Returns > > +- None > > Can we leave this implicit? > > > +Description: Adds animation type > > Why type? Seems to be adding an Animation instance. > > > +Parameters > > +- None > > Can we leave this implicit? > > > +Description: Stops animation, removes animation type > > See above. > > > +Description: Records starting time, sets timeout_sid > > Docstrings should describe functionality, not explain the implementation. > > > +class Animation(object): > > Watch out adding trailing spaces > > > +Description: Updates frame, ends after t=duration > > PEP 257 says to use the first line for the one-line summary. > > Are you using any documented guidelines for the format of the docstrings? > > I would _strongly_ advise to start by adding docstrings to packages > and modules. And only once that's done then get to classes and other > top-level elements, then finally to methods. > > If you try to document the details before understanding the big > picture, you are likely to fail. > > Regards, > > Tomeu > > > Regards, > > Kandarp. > > > > > > ___ > > Sugar-devel mailing list > > Sugar-devel@lists.sugarlabs.org > > http://lists.sugarlabs.org/listinfo/sugar-devel > > > > > ___ Sugar-devel mailing list Sugar-devel@lists.sugarlabs.org http://lists.sugarlabs.org/listinfo/sugar-devel
Re: [Sugar-devel] Patch for documentation of graphics/animator.py
Hi Kandarp, some comments follow inline. On Mon, Aug 30, 2010 at 20:46, Kandarp Kaushik wrote: > Tomeu, > Thank you for the pointers. > As recommended, we developed the devtutor activity, and uploaded its source > code at http://git.sugarlabs.org/projects/devtutor. This is an activity to > help understand the Sugar APIs for the developers. > We did get a strong insight on key areas of activity development while > working on this activity. > We also revised the patch based on your feedback and recommendations. Thank > you for your time. We are using PEP 257 as the documentation standard. > Please have a look at the revised patch, and let us know your feedback > - http://seeta.in/dextrose/API%20patch/. +"""Stop animation, remove animation instance.""" Maybe "remove all animation instances" instead? +"""Reset timeout_sid.""" timeout_sid is an implementation detail. I'm not sure we can do much better than saying "Stops animation", maybe mentioning it will emit the 'completed' signal if the animation was running. +Description: Update frame after small time gaps, end after t=duration I would find more useful to say: "Update animation to the next frame" +Description: pass This method is intended to be overridden by subclasses. We should say so or leave it undocumented for now. > Hope it meets the requisite standards. If not, we'll be happy to revise it. > As discussed with you on IRC, our next step is to add documentation of > modules like sugar.graphics. I really think it will be a much better place to start with rather than animator.py. Regards, Tomeu > Regards, > Kandarp > On Sun, Aug 15, 2010 at 7:51 PM, Tomeu Vizoso wrote: >> >> On Sat, Aug 14, 2010 at 18:02, wrote: >> > Hello all, >> > >> > I've made some changes to the docstrings in graphics/animator.py for its >> > documentation and have uploaded the HTML generated using sphinx at: >> > http://seeta.in/sugar/api/documentation/desttemp/html2/animator.html >> > >> > You can compare it with the initial one at: >> > http://api.sugarlabs.org/sphinx/animator.html >> > >> > Attaching the original and new animator.py files along with the patch >> > generated using 'git format-patch master' >> > >> > I've also made a spreadsheet for the documentation and am maintaining it >> > at >> > >> > https://spreadsheets.google.com/a/seeta.in/ccc?key=0AjslliQkdNyvdFZjWnNwcEZzSC1fMkt6ZDlOOUFFMUE&hl=en#gid=0 >> > Attaching it. >> > >> > Please see if you would like to help or let me know in case of any >> > suggestions/feedback. >> >> Hi Kandarp, some suggestions follow: >> >> > Subject: [PATCH] description of animator.py >> >> The docstring for the module animator.py isn't really included in this >> patch. >> >> > animator1.py | 69 >> > ++--- >> >> This is very weird as there's no animator1.py file in sugar-toolkit. >> Please go through a git tutorial first, we'll all save time. >> >> > + :Inherits: gobject.GObject >> >> Sphinx cannot get this information from the code? Is it common >> practice in sphinx-generated docs? >> >> > + Returns >> > + - None >> >> Can we leave this implicit? >> >> > + Description: Adds animation type >> >> Why type? Seems to be adding an Animation instance. >> >> > + Parameters >> > + - None >> >> Can we leave this implicit? >> >> > + Description: Stops animation, removes animation type >> >> See above. >> >> > + Description: Records starting time, sets timeout_sid >> >> Docstrings should describe functionality, not explain the implementation. >> >> > +class Animation(object): >> >> Watch out adding trailing spaces >> >> > + Description: Updates frame, ends after t=duration >> >> PEP 257 says to use the first line for the one-line summary. >> >> Are you using any documented guidelines for the format of the docstrings? >> >> I would _strongly_ advise to start by adding docstrings to packages >> and modules. And only once that's done then get to classes and other >> top-level elements, then finally to methods. >> >> If you try to document the details before understanding the big >> picture, you are likely to fail. >> >> Regards, >> >> Tomeu >> >> > Regards, >> > Kandarp. >> > >> > >> > ___ >> > Sugar-devel mailing list >> > Sugar-devel@lists.sugarlabs.org >> > http://lists.sugarlabs.org/listinfo/sugar-devel >> > >> > > > ___ Sugar-devel mailing list Sugar-devel@lists.sugarlabs.org http://lists.sugarlabs.org/listinfo/sugar-devel
