source: stamper/docs/_build/html/_sources/using.txt@ 43:b086c7d68163

Last change on this file since 43:b086c7d68163 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: 4.3 KB
Line 
1How to use it
2=============
3
4.. contents::
5
6
7Recording time
8--------------
9
10To start recording time::
11
12 stamp
13
14To stop recording time::
15
16 stamp ID DESCRIPTION
17
18where:
19
20- **ID** is a string **without spaces** identifying a customer, project,
21 group of tasks or any other thing you want to use to group your stamps
22
23- **DESCRIPTION** is a description of what you did
24
25for example::
26
27 stamp stamper writing documentation
28
29or::
30
31 stamp stamper implementing per-month line charts
32
33
34Recording consecutive stamps
35++++++++++++++++++++++++++++
36
37Imagine you start working on a project, you *stamp* your start::
38
39 stamp
40
41and then you finish a given task, so you *stamp* it::
42
43 stamp stamper writing installation instructions
44
45but then, you keep yourself working on the same project, but on some other
46task. You don't have to *stamp* the start time again, you simply *stamp* again
47when you finish the work on that other task::
48
49 stamp stamper writing usage instructions
50
51.. note::
52
53 This apply also for changing to another project, you don't have to *stamp*
54 the start time again, just keep stamping the end times. In such a situation,
55 Stamper will take the end time of a recorded stamp as the start time of the
56 next one.
57
58
59Retrieving information from the existing stamps
60-----------------------------------------------
61
62Total times
63+++++++++++
64
65- Get a list of total times stamped per **ID**::
66
67 stamps
68
69- Get the total times stamped for a given **ID**, for example, **stamper**::
70
71 stamps stamper
72
73- Get the total times stamped for the **ID** **stamper** during the last
74 week::
75
76 stamps stamper 1w
77
78 .. seealso::
79
80 *1w* is a date-based filter. You can learn more about those filters
81 in the :ref:`date_based_filtering` documentation below.
82
83Per day details
84+++++++++++++++
85
86- Get a list of detailed per-day times::
87
88 stamps -v
89
90- Get details for a given **ID**, for example, **stamper**::
91
92 stamps -v stamper
93
94- Get details for a given month, for example, *august 2014*::
95
96 stamps -v 2014-08-01--2014-09-01
97
98 .. seealso::
99
100 *2014-08-01--2014-09-01* is a date-based filter. You can learn more about
101 those filters in the :ref:`date_based_filtering` documentation below.
102
103Timeline
104++++++++
105
106You can get a *timeline* of all the stamped stamps::
107
108 stamps -t
109
110This *timeline* will show each stamp in a line, in a similar way to what bebu's
111stamp [1]_ stores in its text-based file::
112
113 2014-08-12 12:33 start
114 2014-08-12 12:51 stamper writing installation instructions
115 2014-08-12 13:11 stamper writing usage documentation
116 2014-08-13 09:33 start
117 2014-08-13 12:12 stamper adding missing tests for the cli tools
118
119You can filter the timeline by **ID**::
120
121 stamps -t stamper
122
123And/or by date::
124
125 stamps -t 2m
126
127 .. seealso::
128
129 *2m* is a date-based filter. You can learn more about those filters
130 in the :ref:`date_based_filtering` documentation below.
131
132
133
134
135Full List of arguments
136++++++++++++++++++++++
137
138.. argparse::
139 :module: stamper.cli
140 :func: build_args_parser
141 :prog: stamper
142
143
144.. _date_based_filtering:
145
146Date-based filtering
147--------------------
148
149Most of the results returned by the *stamps* tool can be filtered using the
150following date-based filters:
151
152- **YYYY-MM-DD**: Limit the results to only those stamps stamped on this date::
153
154 stamps -v 2014-08-13
155
156 ::
157
158 stamps -t stamper 2014-08-13
159
160- **YYYY-MM-DD\***: Limit the results to only those stamps stamped **after this
161 date**. For example, this will show per-day details for stamps stamped after
162 the first of august, 2014::
163
164 stamps -v 2014-08-01*
165
166- **\*YYYY-MM-DD**: Limit the results to only those stamps stamped **before this
167 date**. For example this will show the total time stamped for project stamper
168 before the first of january, 2014::
169
170 stamps stamper *2014-01-01
171
172- **YYYY-MM-DD--YYYY-MM-DD**: Limit the results to only those stamps stamped in
173 a date **between those dates**. For example, this will show the *timeline* for
174 july, 2014::
175
176 stamps -t 2014-07-01--2014-08-01
177
178- **nD|W|M|Y**: Limit the results to only those stamps stamped since n *days*
179 (**D**), *weeks* (**W**), *months* (**M**) or *years* (**Y**) ago.
180 For example, this will show the details for the last month::
181
182 stamps -v 1m
183
184 .. note::
185
186 It does not matter if you provide *d|w|m|y* or *D|W|M|Y*. The filters are
187 handled in a case-insensitive way.
188
189
190.. [1] http://repos.betabug.ch/stamp
Note: See TracBrowser for help on using the repository browser.