source: stamper/docs/_build/html/using.html@ 47:c38a9fd74e17

Last change on this file since 47:c38a9fd74e17 was 44:5f48fc9d6e7d, checked in by Borja Lopez <borja@…>, 10 years ago

Added charts generation documentation

Added information on how to get the list of full arguments on the command
line for the stamps tool
File size: 18.5 KB
RevLine 
[42]1<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
2 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
3
4
5<html xmlns="http://www.w3.org/1999/xhtml">
6 <head>
7 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
8
9 <title>How to use it &mdash; Stamper 0.1 documentation</title>
10
11 <link rel="stylesheet" href="_static/default.css" type="text/css" />
12 <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
13
14 <script type="text/javascript">
15 var DOCUMENTATION_OPTIONS = {
16 URL_ROOT: './',
17 VERSION: '0.1',
18 COLLAPSE_INDEX: false,
19 FILE_SUFFIX: '.html',
20 HAS_SOURCE: true
21 };
22 </script>
23 <script type="text/javascript" src="_static/jquery.js"></script>
24 <script type="text/javascript" src="_static/underscore.js"></script>
25 <script type="text/javascript" src="_static/doctools.js"></script>
26 <link rel="author" title="About these documents" href="about.html" />
27 <link rel="top" title="Stamper 0.1 documentation" href="index.html" />
28 <link rel="prev" title="Installation instructions" href="install.html" />
29 </head>
30 <body>
31 <div class="related">
32 <h3>Navigation</h3>
33 <ul>
34 <li class="right" style="margin-right: 10px">
35 <a href="genindex.html" title="General Index"
36 accesskey="I">index</a></li>
37 <li class="right" >
38 <a href="install.html" title="Installation instructions"
39 accesskey="P">previous</a> |</li>
40 <li><a href="index.html">Stamper 0.1 documentation</a> &raquo;</li>
41 </ul>
42 </div>
43
44 <div class="document">
45 <div class="documentwrapper">
46 <div class="bodywrapper">
47 <div class="body">
48
49 <div class="section" id="how-to-use-it">
50<h1><a class="toc-backref" href="#id4">How to use it</a><a class="headerlink" href="#how-to-use-it" title="Permalink to this headline"></a></h1>
51<div class="contents topic" id="contents">
52<p class="topic-title first">Contents</p>
53<ul class="simple">
54<li><a class="reference internal" href="#how-to-use-it" id="id4">How to use it</a><ul>
55<li><a class="reference internal" href="#recording-time" id="id5">Recording time</a><ul>
56<li><a class="reference internal" href="#recording-consecutive-stamps" id="id6">Recording consecutive stamps</a></li>
57</ul>
58</li>
59<li><a class="reference internal" href="#retrieving-information-from-the-existing-stamps" id="id7">Retrieving information from the existing stamps</a><ul>
60<li><a class="reference internal" href="#total-times" id="id8">Total times</a></li>
61<li><a class="reference internal" href="#per-day-details" id="id9">Per day details</a></li>
62<li><a class="reference internal" href="#timeline" id="id10">Timeline</a></li>
[44]63<li><a class="reference internal" href="#charts" id="id11">Charts</a></li>
[42]64</ul>
65</li>
[44]66<li><a class="reference internal" href="#stamps-full-list-of-arguments" id="id12">stamps - full List of arguments</a></li>
67<li><a class="reference internal" href="#date-based-filtering" id="id13">Date-based filtering</a></li>
[42]68</ul>
69</li>
70</ul>
71</div>
72<div class="section" id="recording-time">
73<h2><a class="toc-backref" href="#id5">Recording time</a><a class="headerlink" href="#recording-time" title="Permalink to this headline"></a></h2>
74<p>To start recording time:</p>
75<div class="highlight-python"><div class="highlight"><pre><span class="n">stamp</span>
76</pre></div>
77</div>
78<p>To stop recording time:</p>
79<div class="highlight-python"><div class="highlight"><pre>stamp ID DESCRIPTION
80</pre></div>
81</div>
82<p>where:</p>
83<ul class="simple">
84<li><strong>ID</strong> is a string <strong>without spaces</strong> identifying a customer, project,
85group of tasks or any other thing you want to use to group your stamps</li>
86<li><strong>DESCRIPTION</strong> is a description of what you did</li>
87</ul>
88<p>for example:</p>
89<div class="highlight-python"><div class="highlight"><pre>stamp stamper writing documentation
90</pre></div>
91</div>
92<p>or:</p>
93<div class="highlight-python"><div class="highlight"><pre>stamp stamper implementing per-month line charts
94</pre></div>
95</div>
96<div class="section" id="recording-consecutive-stamps">
97<h3><a class="toc-backref" href="#id6">Recording consecutive stamps</a><a class="headerlink" href="#recording-consecutive-stamps" title="Permalink to this headline"></a></h3>
98<p>Imagine you start working on a project, you <em>stamp</em> your start:</p>
99<div class="highlight-python"><div class="highlight"><pre><span class="n">stamp</span>
100</pre></div>
101</div>
102<p>and then you finish a given task, so you <em>stamp</em> it:</p>
103<div class="highlight-python"><div class="highlight"><pre>stamp stamper writing installation instructions
104</pre></div>
105</div>
106<p>but then, you keep yourself working on the same project, but on some other
107task. You don&#8217;t have to <em>stamp</em> the start time again, you simply <em>stamp</em> again
108when you finish the work on that other task:</p>
109<div class="highlight-python"><div class="highlight"><pre>stamp stamper writing usage instructions
110</pre></div>
111</div>
112<div class="admonition note">
113<p class="first admonition-title">Note</p>
114<p class="last">This apply also for changing to another project, you don&#8217;t have to <em>stamp</em>
115the start time again, just keep stamping the end times. In such a situation,
116Stamper will take the end time of a recorded stamp as the start time of the
117next one.</p>
118</div>
119</div>
120</div>
121<div class="section" id="retrieving-information-from-the-existing-stamps">
122<h2><a class="toc-backref" href="#id7">Retrieving information from the existing stamps</a><a class="headerlink" href="#retrieving-information-from-the-existing-stamps" title="Permalink to this headline"></a></h2>
123<div class="section" id="total-times">
124<h3><a class="toc-backref" href="#id8">Total times</a><a class="headerlink" href="#total-times" title="Permalink to this headline"></a></h3>
125<ul>
126<li><p class="first">Get a list of total times stamped per <strong>ID</strong>:</p>
127<div class="highlight-python"><div class="highlight"><pre><span class="n">stamps</span>
128</pre></div>
129</div>
130</li>
131<li><p class="first">Get the total times stamped for a given <strong>ID</strong>, for example, <strong>stamper</strong>:</p>
132<div class="highlight-python"><div class="highlight"><pre>stamps stamper
133</pre></div>
134</div>
135</li>
136<li><p class="first">Get the total times stamped for the <strong>ID</strong> <strong>stamper</strong> during the last
137week:</p>
138<div class="highlight-python"><div class="highlight"><pre>stamps stamper 1w
139</pre></div>
140</div>
141<div class="admonition seealso">
142<p class="first admonition-title">See also</p>
143<p class="last"><em>1w</em> is a date-based filter. You can learn more about those filters
144in the <a class="reference internal" href="#date-based-filtering"><em>Date-based filtering</em></a> documentation below.</p>
145</div>
146</li>
147</ul>
148</div>
149<div class="section" id="per-day-details">
150<h3><a class="toc-backref" href="#id9">Per day details</a><a class="headerlink" href="#per-day-details" title="Permalink to this headline"></a></h3>
151<ul>
152<li><p class="first">Get a list of detailed per-day times:</p>
153<div class="highlight-python"><div class="highlight"><pre><span class="n">stamps</span> <span class="o">-</span><span class="n">v</span>
154</pre></div>
155</div>
156</li>
157<li><p class="first">Get details for a given <strong>ID</strong>, for example, <strong>stamper</strong>:</p>
158<div class="highlight-python"><div class="highlight"><pre>stamps -v stamper
159</pre></div>
160</div>
161</li>
162<li><p class="first">Get details for a given month, for example, <em>august 2014</em>:</p>
163<div class="highlight-python"><div class="highlight"><pre>stamps -v 2014-08-01--2014-09-01
164</pre></div>
165</div>
166<div class="admonition seealso">
167<p class="first admonition-title">See also</p>
168<p class="last"><em>2014-08-01&#8211;2014-09-01</em> is a date-based filter. You can learn more about
169those filters in the <a class="reference internal" href="#date-based-filtering"><em>Date-based filtering</em></a> documentation below.</p>
170</div>
171</li>
172</ul>
173</div>
174<div class="section" id="timeline">
175<h3><a class="toc-backref" href="#id10">Timeline</a><a class="headerlink" href="#timeline" title="Permalink to this headline"></a></h3>
176<p>You can get a <em>timeline</em> of all the stamped stamps:</p>
177<div class="highlight-python"><div class="highlight"><pre><span class="n">stamps</span> <span class="o">-</span><span class="n">t</span>
178</pre></div>
179</div>
180<p>This <em>timeline</em> will show each stamp in a line, in a similar way to what bebu&#8217;s
181stamp <a class="footnote-reference" href="#id3" id="id1">[1]</a> stores in its text-based file:</p>
182<div class="highlight-python"><div class="highlight"><pre>2014-08-12 12:33 start
1832014-08-12 12:51 stamper writing installation instructions
1842014-08-12 13:11 stamper writing usage documentation
1852014-08-13 09:33 start
1862014-08-13 12:12 stamper adding missing tests for the cli tools
187</pre></div>
188</div>
189<p>You can filter the timeline by <strong>ID</strong>:</p>
190<div class="highlight-python"><div class="highlight"><pre>stamps -t stamper
191</pre></div>
192</div>
193<p>And/or by date:</p>
194<div class="highlight-python"><div class="highlight"><pre>stamps -t 2m
195
196.. seealso::
197
198 *2m* is a date-based filter. You can learn more about those filters
199 in the :ref:`date_based_filtering` documentation below.
200</pre></div>
201</div>
202</div>
[44]203<div class="section" id="charts">
204<h3><a class="toc-backref" href="#id11">Charts</a><a class="headerlink" href="#charts" title="Permalink to this headline"></a></h3>
205<p>You can generate some nice charts from your stamps. So far only bar charts
206showing the total time per day can be generated, but you can filter them by
207<strong>ID</strong> and/or date. Some examples:</p>
208<ul>
209<li><p class="first">Render a chart of all the times already stamped, by <strong>ID</strong>:</p>
210<div class="highlight-python"><div class="highlight"><pre><span class="n">stamps</span> <span class="o">-</span><span class="n">g</span>
211</pre></div>
212</div>
213</li>
214<li><p class="first">Render a chart of the stamps for the last 4 days:</p>
215<div class="highlight-python"><div class="highlight"><pre>stamps -g 4d
216</pre></div>
217</div>
218</li>
219<li><p class="first">Render a chart of the stamps for the <strong>ID</strong> <em>stamper</em> for the last week:</p>
220<div class="highlight-python"><div class="highlight"><pre>stamps -g stamper 1w
221</pre></div>
222</div>
223</li>
224</ul>
225<div class="admonition note">
226<p class="first admonition-title">Note</p>
227<p class="last">The charts will be saved into <strong>~/.workstamps-charts</strong>, in <a class="reference external" href="http://en.wikipedia.org/wiki/Scalable_Vector_Graphics">SVG</a> format.
228The name of the chart will be generated based on the current date and
229time, and a <em>symbolic link</em> called <strong>chart-latest.svg</strong> will be created,
230pointing to the latest chart generated.</p>
231</div>
232</div>
233</div>
234<div class="section" id="stamps-full-list-of-arguments">
235<h2><a class="toc-backref" href="#id12">stamps - full List of arguments</a><a class="headerlink" href="#stamps-full-list-of-arguments" title="Permalink to this headline"></a></h2>
236<p>You can get the full list of arguments from the command line too:</p>
237<div class="highlight-python"><div class="highlight"><pre><span class="n">stamps</span> <span class="o">-</span><span class="n">h</span>
238</pre></div>
239</div>
240<p>or:</p>
241<div class="highlight-python"><div class="highlight"><pre><span class="n">stamps</span> <span class="o">--</span><span class="n">help</span>
242</pre></div>
243</div>
[42]244<p>stamps: show recorded times information</p>
245<pre class="literal-block">
246usage: stamper [-h] [-v] [-s] [-g] [-t] [-d DELETE] [-i IMPORT_FILE]
247 [customer] [filter]
248</pre>
249<dl class="docutils">
250<dt>Positional arguments:</dt>
251<dd><table class="first last docutils option-list" frame="void" rules="none">
252<col class="option" />
253<col class="description" />
254<tbody valign="top">
255<tr><td class="option-group">
256<kbd>customer</kbd></td>
257<td>Show times only for this customer</td></tr>
258<tr><td class="option-group">
259<kbd>filter</kbd></td>
260<td>Filter the times by date range</td></tr>
261</tbody>
262</table>
263</dd>
264<dt>Options:</dt>
265<dd><table class="first last docutils option-list" frame="void" rules="none">
266<col class="option" />
267<col class="description" />
268<tbody valign="top">
269<tr><td class="option-group" colspan="2">
270<kbd><span class="option">-v=False</span>, <span class="option">--verbose=False</span></kbd></td>
271</tr>
272<tr><td>&nbsp;</td><td>Include detailed times information</td></tr>
273<tr><td class="option-group" colspan="2">
274<kbd><span class="option">-s=False</span>, <span class="option">--sum=False</span></kbd></td>
275</tr>
276<tr><td>&nbsp;</td><td>Include sum of times</td></tr>
277<tr><td class="option-group" colspan="2">
278<kbd><span class="option">-g=False</span>, <span class="option">--graph=False</span></kbd></td>
279</tr>
280<tr><td>&nbsp;</td><td>Generate a SVG graph</td></tr>
281<tr><td class="option-group" colspan="2">
282<kbd><span class="option">-t=False</span>, <span class="option">--timeline=False</span></kbd></td>
283</tr>
284<tr><td>&nbsp;</td><td>Show a timeline of recorded times</td></tr>
285<tr><td class="option-group">
286<kbd><span class="option">-d</span>, <span class="option">--delete</span></kbd></td>
287<td>Delete up to n recorded stamps</td></tr>
288<tr><td class="option-group">
289<kbd><span class="option">-i</span>, <span class="option">--import</span></kbd></td>
290<td>Import stamps from the given file</td></tr>
291</tbody>
292</table>
293</dd>
294</dl>
295</div>
296<div class="section" id="date-based-filtering">
[44]297<span id="id2"></span><h2><a class="toc-backref" href="#id13">Date-based filtering</a><a class="headerlink" href="#date-based-filtering" title="Permalink to this headline"></a></h2>
[42]298<p>Most of the results returned by the <em>stamps</em> tool can be filtered using the
299following date-based filters:</p>
300<ul>
301<li><p class="first"><strong>YYYY-MM-DD</strong>: Limit the results to only those stamps stamped on this date:</p>
302<div class="highlight-python"><div class="highlight"><pre>stamps -v 2014-08-13
303</pre></div>
304</div>
305<div class="highlight-python"><div class="highlight"><pre>stamps -t stamper 2014-08-13
306</pre></div>
307</div>
308</li>
309<li><p class="first"><strong>YYYY-MM-DD*</strong>: Limit the results to only those stamps stamped <strong>after this
310date</strong>. For example, this will show per-day details for stamps stamped after
311the first of august, 2014:</p>
312<div class="highlight-python"><div class="highlight"><pre>stamps -v 2014-08-01*
313</pre></div>
314</div>
315</li>
316<li><p class="first"><strong>*YYYY-MM-DD</strong>: Limit the results to only those stamps stamped <strong>before this
317date</strong>. For example this will show the total time stamped for project stamper
318before the first of january, 2014:</p>
319<div class="highlight-python"><div class="highlight"><pre>stamps stamper *2014-01-01
320</pre></div>
321</div>
322</li>
323<li><p class="first"><strong>YYYY-MM-DD&#8211;YYYY-MM-DD</strong>: Limit the results to only those stamps stamped in
324a date <strong>between those dates</strong>. For example, this will show the <em>timeline</em> for
325july, 2014:</p>
326<div class="highlight-python"><div class="highlight"><pre>stamps -t 2014-07-01--2014-08-01
327</pre></div>
328</div>
329</li>
330<li><p class="first"><strong>nD|W|M|Y</strong>: Limit the results to only those stamps stamped since n <em>days</em>
331(<strong>D</strong>), <em>weeks</em> (<strong>W</strong>), <em>months</em> (<strong>M</strong>) or <em>years</em> (<strong>Y</strong>) ago.
332For example, this will show the details for the last month:</p>
333<div class="highlight-python"><div class="highlight"><pre>stamps -v 1m
334</pre></div>
335</div>
336<div class="admonition note">
337<p class="first admonition-title">Note</p>
338<p class="last">It does not matter if you provide <em>d|w|m|y</em> or <em>D|W|M|Y</em>. The filters are
339handled in a case-insensitive way.</p>
340</div>
341</li>
342</ul>
343<table class="docutils footnote" frame="void" id="id3" rules="none">
344<colgroup><col class="label" /><col /></colgroup>
345<tbody valign="top">
346<tr><td class="label"><a class="fn-backref" href="#id1">[1]</a></td><td><a class="reference external" href="http://repos.betabug.ch/stamp">http://repos.betabug.ch/stamp</a></td></tr>
347</tbody>
348</table>
349</div>
350</div>
351
352
353 </div>
354 </div>
355 </div>
356 <div class="sphinxsidebar">
357 <div class="sphinxsidebarwrapper">
358 <h3><a href="index.html">Table Of Contents</a></h3>
359 <ul>
360<li><a class="reference internal" href="#">How to use it</a><ul>
361<li><a class="reference internal" href="#recording-time">Recording time</a><ul>
362<li><a class="reference internal" href="#recording-consecutive-stamps">Recording consecutive stamps</a></li>
363</ul>
364</li>
365<li><a class="reference internal" href="#retrieving-information-from-the-existing-stamps">Retrieving information from the existing stamps</a><ul>
366<li><a class="reference internal" href="#total-times">Total times</a></li>
367<li><a class="reference internal" href="#per-day-details">Per day details</a></li>
368<li><a class="reference internal" href="#timeline">Timeline</a></li>
[44]369<li><a class="reference internal" href="#charts">Charts</a></li>
[42]370</ul>
371</li>
[44]372<li><a class="reference internal" href="#stamps-full-list-of-arguments">stamps - full List of arguments</a></li>
[42]373<li><a class="reference internal" href="#date-based-filtering">Date-based filtering</a></li>
374</ul>
375</li>
376</ul>
377
378 <h4>Previous topic</h4>
379 <p class="topless"><a href="install.html"
380 title="previous chapter">Installation instructions</a></p>
381 <h3>This Page</h3>
382 <ul class="this-page-menu">
383 <li><a href="_sources/using.txt"
384 rel="nofollow">Show Source</a></li>
385 </ul>
386<div id="searchbox" style="display: none">
387 <h3>Quick search</h3>
388 <form class="search" action="search.html" method="get">
389 <input type="text" name="q" />
390 <input type="submit" value="Go" />
391 <input type="hidden" name="check_keywords" value="yes" />
392 <input type="hidden" name="area" value="default" />
393 </form>
394 <p class="searchtip" style="font-size: 90%">
395 Enter search terms or a module, class or function name.
396 </p>
397</div>
398<script type="text/javascript">$('#searchbox').show(0);</script>
399 </div>
400 </div>
401 <div class="clearer"></div>
402 </div>
403 <div class="related">
404 <h3>Navigation</h3>
405 <ul>
406 <li class="right" style="margin-right: 10px">
407 <a href="genindex.html" title="General Index"
408 >index</a></li>
409 <li class="right" >
410 <a href="install.html" title="Installation instructions"
411 >previous</a> |</li>
412 <li><a href="index.html">Stamper 0.1 documentation</a> &raquo;</li>
413 </ul>
414 </div>
415 <div class="footer">
416 &copy; Copyright 2014, Fco. de Borja Lopez Rio, Oscar M. Lage.
417 Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
418 </div>
419 </body>
420</html>
Note: See TracBrowser for help on using the repository browser.