source: stamper/docs/_build/html/using.html@ 42:cff2c17bc1d4

Last change on this file since 42:cff2c17bc1d4 was 42:cff2c17bc1d4, checked in by Borja Lopez <borja@…>, 10 years ago

Added initial version of the docs, covering:

  • About stamper
  • Basic installation instructions (missing install from repo or dev env setup, for example)
  • Basic usage instructions (total times, per-day details, timeline, date-based filters and more)
File size: 16.4 KB
Line 
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>
63<li><a class="reference internal" href="#full-list-of-arguments" id="id11">Full List of arguments</a></li>
64</ul>
65</li>
66<li><a class="reference internal" href="#date-based-filtering" id="id12">Date-based filtering</a></li>
67</ul>
68</li>
69</ul>
70</div>
71<div class="section" id="recording-time">
72<h2><a class="toc-backref" href="#id5">Recording time</a><a class="headerlink" href="#recording-time" title="Permalink to this headline"></a></h2>
73<p>To start recording time:</p>
74<div class="highlight-python"><div class="highlight"><pre><span class="n">stamp</span>
75</pre></div>
76</div>
77<p>To stop recording time:</p>
78<div class="highlight-python"><div class="highlight"><pre>stamp ID DESCRIPTION
79</pre></div>
80</div>
81<p>where:</p>
82<ul class="simple">
83<li><strong>ID</strong> is a string <strong>without spaces</strong> identifying a customer, project,
84group of tasks or any other thing you want to use to group your stamps</li>
85<li><strong>DESCRIPTION</strong> is a description of what you did</li>
86</ul>
87<p>for example:</p>
88<div class="highlight-python"><div class="highlight"><pre>stamp stamper writing documentation
89</pre></div>
90</div>
91<p>or:</p>
92<div class="highlight-python"><div class="highlight"><pre>stamp stamper implementing per-month line charts
93</pre></div>
94</div>
95<div class="section" id="recording-consecutive-stamps">
96<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>
97<p>Imagine you start working on a project, you <em>stamp</em> your start:</p>
98<div class="highlight-python"><div class="highlight"><pre><span class="n">stamp</span>
99</pre></div>
100</div>
101<p>and then you finish a given task, so you <em>stamp</em> it:</p>
102<div class="highlight-python"><div class="highlight"><pre>stamp stamper writing installation instructions
103</pre></div>
104</div>
105<p>but then, you keep yourself working on the same project, but on some other
106task. You don&#8217;t have to <em>stamp</em> the start time again, you simply <em>stamp</em> again
107when you finish the work on that other task:</p>
108<div class="highlight-python"><div class="highlight"><pre>stamp stamper writing usage instructions
109</pre></div>
110</div>
111<div class="admonition note">
112<p class="first admonition-title">Note</p>
113<p class="last">This apply also for changing to another project, you don&#8217;t have to <em>stamp</em>
114the start time again, just keep stamping the end times. In such a situation,
115Stamper will take the end time of a recorded stamp as the start time of the
116next one.</p>
117</div>
118</div>
119</div>
120<div class="section" id="retrieving-information-from-the-existing-stamps">
121<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>
122<div class="section" id="total-times">
123<h3><a class="toc-backref" href="#id8">Total times</a><a class="headerlink" href="#total-times" title="Permalink to this headline"></a></h3>
124<ul>
125<li><p class="first">Get a list of total times stamped per <strong>ID</strong>:</p>
126<div class="highlight-python"><div class="highlight"><pre><span class="n">stamps</span>
127</pre></div>
128</div>
129</li>
130<li><p class="first">Get the total times stamped for a given <strong>ID</strong>, for example, <strong>stamper</strong>:</p>
131<div class="highlight-python"><div class="highlight"><pre>stamps stamper
132</pre></div>
133</div>
134</li>
135<li><p class="first">Get the total times stamped for the <strong>ID</strong> <strong>stamper</strong> during the last
136week:</p>
137<div class="highlight-python"><div class="highlight"><pre>stamps stamper 1w
138</pre></div>
139</div>
140<div class="admonition seealso">
141<p class="first admonition-title">See also</p>
142<p class="last"><em>1w</em> is a date-based filter. You can learn more about those filters
143in the <a class="reference internal" href="#date-based-filtering"><em>Date-based filtering</em></a> documentation below.</p>
144</div>
145</li>
146</ul>
147</div>
148<div class="section" id="per-day-details">
149<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>
150<ul>
151<li><p class="first">Get a list of detailed per-day times:</p>
152<div class="highlight-python"><div class="highlight"><pre><span class="n">stamps</span> <span class="o">-</span><span class="n">v</span>
153</pre></div>
154</div>
155</li>
156<li><p class="first">Get details for a given <strong>ID</strong>, for example, <strong>stamper</strong>:</p>
157<div class="highlight-python"><div class="highlight"><pre>stamps -v stamper
158</pre></div>
159</div>
160</li>
161<li><p class="first">Get details for a given month, for example, <em>august 2014</em>:</p>
162<div class="highlight-python"><div class="highlight"><pre>stamps -v 2014-08-01--2014-09-01
163</pre></div>
164</div>
165<div class="admonition seealso">
166<p class="first admonition-title">See also</p>
167<p class="last"><em>2014-08-01&#8211;2014-09-01</em> is a date-based filter. You can learn more about
168those filters in the <a class="reference internal" href="#date-based-filtering"><em>Date-based filtering</em></a> documentation below.</p>
169</div>
170</li>
171</ul>
172</div>
173<div class="section" id="timeline">
174<h3><a class="toc-backref" href="#id10">Timeline</a><a class="headerlink" href="#timeline" title="Permalink to this headline"></a></h3>
175<p>You can get a <em>timeline</em> of all the stamped stamps:</p>
176<div class="highlight-python"><div class="highlight"><pre><span class="n">stamps</span> <span class="o">-</span><span class="n">t</span>
177</pre></div>
178</div>
179<p>This <em>timeline</em> will show each stamp in a line, in a similar way to what bebu&#8217;s
180stamp <a class="footnote-reference" href="#id3" id="id1">[1]</a> stores in its text-based file:</p>
181<div class="highlight-python"><div class="highlight"><pre>2014-08-12 12:33 start
1822014-08-12 12:51 stamper writing installation instructions
1832014-08-12 13:11 stamper writing usage documentation
1842014-08-13 09:33 start
1852014-08-13 12:12 stamper adding missing tests for the cli tools
186</pre></div>
187</div>
188<p>You can filter the timeline by <strong>ID</strong>:</p>
189<div class="highlight-python"><div class="highlight"><pre>stamps -t stamper
190</pre></div>
191</div>
192<p>And/or by date:</p>
193<div class="highlight-python"><div class="highlight"><pre>stamps -t 2m
194
195.. seealso::
196
197 *2m* is a date-based filter. You can learn more about those filters
198 in the :ref:`date_based_filtering` documentation below.
199</pre></div>
200</div>
201</div>
202<div class="section" id="full-list-of-arguments">
203<h3><a class="toc-backref" href="#id11">Full List of arguments</a><a class="headerlink" href="#full-list-of-arguments" title="Permalink to this headline"></a></h3>
204<p>stamps: show recorded times information</p>
205<pre class="literal-block">
206usage: stamper [-h] [-v] [-s] [-g] [-t] [-d DELETE] [-i IMPORT_FILE]
207 [customer] [filter]
208</pre>
209<dl class="docutils">
210<dt>Positional arguments:</dt>
211<dd><table class="first last docutils option-list" frame="void" rules="none">
212<col class="option" />
213<col class="description" />
214<tbody valign="top">
215<tr><td class="option-group">
216<kbd>customer</kbd></td>
217<td>Show times only for this customer</td></tr>
218<tr><td class="option-group">
219<kbd>filter</kbd></td>
220<td>Filter the times by date range</td></tr>
221</tbody>
222</table>
223</dd>
224<dt>Options:</dt>
225<dd><table class="first last docutils option-list" frame="void" rules="none">
226<col class="option" />
227<col class="description" />
228<tbody valign="top">
229<tr><td class="option-group" colspan="2">
230<kbd><span class="option">-v=False</span>, <span class="option">--verbose=False</span></kbd></td>
231</tr>
232<tr><td>&nbsp;</td><td>Include detailed times information</td></tr>
233<tr><td class="option-group" colspan="2">
234<kbd><span class="option">-s=False</span>, <span class="option">--sum=False</span></kbd></td>
235</tr>
236<tr><td>&nbsp;</td><td>Include sum of times</td></tr>
237<tr><td class="option-group" colspan="2">
238<kbd><span class="option">-g=False</span>, <span class="option">--graph=False</span></kbd></td>
239</tr>
240<tr><td>&nbsp;</td><td>Generate a SVG graph</td></tr>
241<tr><td class="option-group" colspan="2">
242<kbd><span class="option">-t=False</span>, <span class="option">--timeline=False</span></kbd></td>
243</tr>
244<tr><td>&nbsp;</td><td>Show a timeline of recorded times</td></tr>
245<tr><td class="option-group">
246<kbd><span class="option">-d</span>, <span class="option">--delete</span></kbd></td>
247<td>Delete up to n recorded stamps</td></tr>
248<tr><td class="option-group">
249<kbd><span class="option">-i</span>, <span class="option">--import</span></kbd></td>
250<td>Import stamps from the given file</td></tr>
251</tbody>
252</table>
253</dd>
254</dl>
255</div>
256</div>
257<div class="section" id="date-based-filtering">
258<span id="id2"></span><h2><a class="toc-backref" href="#id12">Date-based filtering</a><a class="headerlink" href="#date-based-filtering" title="Permalink to this headline"></a></h2>
259<p>Most of the results returned by the <em>stamps</em> tool can be filtered using the
260following date-based filters:</p>
261<ul>
262<li><p class="first"><strong>YYYY-MM-DD</strong>: Limit the results to only those stamps stamped on this date:</p>
263<div class="highlight-python"><div class="highlight"><pre>stamps -v 2014-08-13
264</pre></div>
265</div>
266<div class="highlight-python"><div class="highlight"><pre>stamps -t stamper 2014-08-13
267</pre></div>
268</div>
269</li>
270<li><p class="first"><strong>YYYY-MM-DD*</strong>: Limit the results to only those stamps stamped <strong>after this
271date</strong>. For example, this will show per-day details for stamps stamped after
272the first of august, 2014:</p>
273<div class="highlight-python"><div class="highlight"><pre>stamps -v 2014-08-01*
274</pre></div>
275</div>
276</li>
277<li><p class="first"><strong>*YYYY-MM-DD</strong>: Limit the results to only those stamps stamped <strong>before this
278date</strong>. For example this will show the total time stamped for project stamper
279before the first of january, 2014:</p>
280<div class="highlight-python"><div class="highlight"><pre>stamps stamper *2014-01-01
281</pre></div>
282</div>
283</li>
284<li><p class="first"><strong>YYYY-MM-DD&#8211;YYYY-MM-DD</strong>: Limit the results to only those stamps stamped in
285a date <strong>between those dates</strong>. For example, this will show the <em>timeline</em> for
286july, 2014:</p>
287<div class="highlight-python"><div class="highlight"><pre>stamps -t 2014-07-01--2014-08-01
288</pre></div>
289</div>
290</li>
291<li><p class="first"><strong>nD|W|M|Y</strong>: Limit the results to only those stamps stamped since n <em>days</em>
292(<strong>D</strong>), <em>weeks</em> (<strong>W</strong>), <em>months</em> (<strong>M</strong>) or <em>years</em> (<strong>Y</strong>) ago.
293For example, this will show the details for the last month:</p>
294<div class="highlight-python"><div class="highlight"><pre>stamps -v 1m
295</pre></div>
296</div>
297<div class="admonition note">
298<p class="first admonition-title">Note</p>
299<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
300handled in a case-insensitive way.</p>
301</div>
302</li>
303</ul>
304<table class="docutils footnote" frame="void" id="id3" rules="none">
305<colgroup><col class="label" /><col /></colgroup>
306<tbody valign="top">
307<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>
308</tbody>
309</table>
310</div>
311</div>
312
313
314 </div>
315 </div>
316 </div>
317 <div class="sphinxsidebar">
318 <div class="sphinxsidebarwrapper">
319 <h3><a href="index.html">Table Of Contents</a></h3>
320 <ul>
321<li><a class="reference internal" href="#">How to use it</a><ul>
322<li><a class="reference internal" href="#recording-time">Recording time</a><ul>
323<li><a class="reference internal" href="#recording-consecutive-stamps">Recording consecutive stamps</a></li>
324</ul>
325</li>
326<li><a class="reference internal" href="#retrieving-information-from-the-existing-stamps">Retrieving information from the existing stamps</a><ul>
327<li><a class="reference internal" href="#total-times">Total times</a></li>
328<li><a class="reference internal" href="#per-day-details">Per day details</a></li>
329<li><a class="reference internal" href="#timeline">Timeline</a></li>
330<li><a class="reference internal" href="#full-list-of-arguments">Full List of arguments</a></li>
331</ul>
332</li>
333<li><a class="reference internal" href="#date-based-filtering">Date-based filtering</a></li>
334</ul>
335</li>
336</ul>
337
338 <h4>Previous topic</h4>
339 <p class="topless"><a href="install.html"
340 title="previous chapter">Installation instructions</a></p>
341 <h3>This Page</h3>
342 <ul class="this-page-menu">
343 <li><a href="_sources/using.txt"
344 rel="nofollow">Show Source</a></li>
345 </ul>
346<div id="searchbox" style="display: none">
347 <h3>Quick search</h3>
348 <form class="search" action="search.html" method="get">
349 <input type="text" name="q" />
350 <input type="submit" value="Go" />
351 <input type="hidden" name="check_keywords" value="yes" />
352 <input type="hidden" name="area" value="default" />
353 </form>
354 <p class="searchtip" style="font-size: 90%">
355 Enter search terms or a module, class or function name.
356 </p>
357</div>
358<script type="text/javascript">$('#searchbox').show(0);</script>
359 </div>
360 </div>
361 <div class="clearer"></div>
362 </div>
363 <div class="related">
364 <h3>Navigation</h3>
365 <ul>
366 <li class="right" style="margin-right: 10px">
367 <a href="genindex.html" title="General Index"
368 >index</a></li>
369 <li class="right" >
370 <a href="install.html" title="Installation instructions"
371 >previous</a> |</li>
372 <li><a href="index.html">Stamper 0.1 documentation</a> &raquo;</li>
373 </ul>
374 </div>
375 <div class="footer">
376 &copy; Copyright 2014, Fco. de Borja Lopez Rio, Oscar M. Lage.
377 Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
378 </div>
379 </body>
380</html>
Note: See TracBrowser for help on using the repository browser.