define the structure of tiempo's man page
This commit is contained in:
Abraham Toriz
parent
78abfa16e6
commit
b617257f0c
|
|
@ -66,98 +66,42 @@ projects/clients/etc.
|
|||
Tutorial
|
||||
--------
|
||||
|
||||
First of all, you can abbreviate all commands to their first letter, so `t in`
|
||||
and `t i` are equivalent.
|
||||
.. note::
|
||||
|
||||
Managing entries
|
||||
................
|
||||
yo, doc this
|
||||
|
||||
Register the start of an activity in the default timesheet with:
|
||||
Commands
|
||||
--------
|
||||
|
||||
t in 'Doing some coding'
|
||||
.. note::
|
||||
|
||||
which sets the activity's start time to the current time. Later when you're done
|
||||
use
|
||||
TODO finish this
|
||||
|
||||
t out
|
||||
t-in
|
||||
....
|
||||
|
||||
to mark it as finished. If you forgot to start the activity before you can do so
|
||||
with:
|
||||
login
|
||||
|
||||
t i --at '20 min ago'
|
||||
Settings
|
||||
--------
|
||||
|
||||
the same applies for `t out`.
|
||||
.. note::
|
||||
|
||||
Edit an entry with
|
||||
|
||||
t edit [options]
|
||||
|
||||
where the options are
|
||||
|
||||
-i, --id <id:i> Alter entry with id <id> instead of the running entry
|
||||
-s, --start <time:qs> Change the start time to <time>
|
||||
-e, --end <time:qs> Change the end time to <time>
|
||||
-a, --append Append to the current note instead of replacing it
|
||||
the delimiter between appended notes is
|
||||
configurable (see configure)
|
||||
-m, --move <sheet> Move to another sheet
|
||||
|
||||
You can remove an entry with
|
||||
|
||||
t kill --id 123
|
||||
|
||||
or an entire timesheet with
|
||||
|
||||
t kill somesheet
|
||||
|
||||
check bellow to see how to get the ids.
|
||||
|
||||
Displaying entries
|
||||
..................
|
||||
|
||||
At any point in time you can check your time spent in the current or other
|
||||
timesheet with:
|
||||
|
||||
t display [options] [SHEET | all | full]
|
||||
|
||||
the available options are
|
||||
|
||||
-v, --ids Print database ids (for use with edit)
|
||||
-s, --start <date:qs> Include entries that start on this date or later
|
||||
-e, --end <date:qs> Include entries that start on this date or earlier
|
||||
-f, --format <format> The output format. Valid built-in formats are
|
||||
chart, text (default), ical, csv, json and ids.
|
||||
Check the docs on defining custom formats bellow.
|
||||
-g, --grep <regexp> Include entries where the note matches this regexp
|
||||
|
||||
Some shortcuts available are:
|
||||
|
||||
`today` - Display entries that started today
|
||||
|
||||
t today [--ids] [--format FMT] [SHEET | all]
|
||||
|
||||
`yesterday` - Display entries that started yesterday
|
||||
|
||||
t yesterday [--ids] [--format FMT] [SHEET | all]
|
||||
|
||||
`week` - Entries of this week so far. The default start of the week is Monday
|
||||
(configurable).
|
||||
|
||||
t week [--ids] [--end DATE] [--format FMT] [SHEET | all]
|
||||
|
||||
`month` - Entries of this month or a specified one.
|
||||
|
||||
t month [--ids] [--start MONTH] [--format FMT] [SHEET | all]
|
||||
describe the settings file
|
||||
|
||||
Per command default formatters
|
||||
..............................
|
||||
|
||||
.. note::
|
||||
|
||||
likely move this to the section above
|
||||
|
||||
**New in 1.4.0**
|
||||
|
||||
It might be the case that you want to use one default formatter for when you use
|
||||
`t week` and a different one for `t month` or `t today`. That's what per-command
|
||||
default formatters are for. To use them just add a `commands` section to your
|
||||
config file and set `default_formatter` on some formatters. This is what it
|
||||
``t week`` and a different one for ``t month`` or ``t today``. That's what per-command
|
||||
default formatters are for. To use them just add a ``commands`` section to your
|
||||
config file and set ``default_formatter`` on some formatters. This is what it
|
||||
would look like:
|
||||
|
||||
**In toml**
|
||||
|
|
@ -180,104 +124,44 @@ would look like:
|
|||
month:
|
||||
default_formatter: ical
|
||||
|
||||
Using different timesheets
|
||||
..........................
|
||||
|
||||
You can organize your activities in different timesheets by first switching to
|
||||
an existing one, then starting an activity:
|
||||
|
||||
t sheet somename
|
||||
t in 'some activity'
|
||||
|
||||
which will also create the timesheet if it doesn't exist.
|
||||
|
||||
List all existing timesheets using
|
||||
|
||||
t list [all]
|
||||
|
||||
(defaults to not showing archive timesheets with names preceded by an
|
||||
underscore)
|
||||
|
||||
Advanced management
|
||||
...................
|
||||
|
||||
You can archive entries from a timesheet using:
|
||||
|
||||
t archive [OPTIONS] [SHEET]
|
||||
|
||||
which defaults to archiving all entries in the current sheet, or you can be more
|
||||
specific using these options:
|
||||
|
||||
-s, --start <date:qs> Include entries that start on this date or later.
|
||||
-e, --end <date:qs> Include entries that start on this date or earlier.
|
||||
-g, --grep <regexp> Include entries where the note matches this regexp.
|
||||
-t, --time <hours> Only archive up to `hours` hours.
|
||||
|
||||
This subcommand will move the selected entries to a hidden timesheet named
|
||||
`_[SHEET]` (the name of the timesheet preceded by an underscore).
|
||||
|
||||
It is possible to access directly the sqlite database using
|
||||
|
||||
t backend
|
||||
|
||||
Configuration
|
||||
.............
|
||||
|
||||
`tiempo` keeps a config file, whose location you can learn usign `t configure`.
|
||||
It is also possible to edit the config file in-place passing arguments to
|
||||
`t configure` like this:
|
||||
|
||||
t c --append-notes-delimiter ';'
|
||||
|
||||
it will print the resulting config file. Beware that it wont keep comments added
|
||||
to the file.
|
||||
|
||||
Commands
|
||||
--------
|
||||
|
||||
where individual commands are described
|
||||
|
||||
t-in
|
||||
....
|
||||
|
||||
login
|
||||
|
||||
Files and paths
|
||||
---------------
|
||||
|
||||
explain the config file, and database path
|
||||
.. note::
|
||||
|
||||
explain the config file, and database path
|
||||
|
||||
Specifying times
|
||||
----------------
|
||||
|
||||
Some arguments accept a time as value, like `t in`'s `--at` or `t d --start`.
|
||||
Some arguments accept a time as value, like ``t in``'s ``--at`` or ``t d --start``.
|
||||
These are the accepted formats:
|
||||
|
||||
**Something similar to ISO format** will be parsed as a time in the computer's
|
||||
timezone.
|
||||
|
||||
* `2021-01-13` a date
|
||||
* `2019-05-03 11:13` a date with portions of a time
|
||||
* ``2021-01-13`` a date
|
||||
* ``2019-05-03 11:13`` a date with portions of a time
|
||||
|
||||
**ISO format with offset or UTC** will be parsed as a time in the specified
|
||||
timezone. Use `Z` for `UTC` and an offset for everything else
|
||||
timezone. Use ``Z`` for ``UTC`` and an offset for everything else
|
||||
|
||||
* `2021-01-13Z`
|
||||
* `2005-10-14 19:20:35+05:00`
|
||||
* ``2021-01-13Z``
|
||||
* ``2005-10-14 19:20:35+05:00``
|
||||
|
||||
**something that looks like an hour** will be parsed as a time in the current
|
||||
day in the computer's timezone. Add `Z` or an offset to specify the timezone.
|
||||
day in the computer's timezone. Add ``Z`` or an offset to specify the timezone.
|
||||
|
||||
* `11:30`
|
||||
* `23:50:45` (with seconds)
|
||||
* ``11:30``
|
||||
* ``23:50:45`` (with seconds)
|
||||
|
||||
**some human times**, for now restricted to time ago:
|
||||
|
||||
* `an hour ago`
|
||||
* `a minute ago`
|
||||
* `50 min ago`
|
||||
* `1h30m ago`
|
||||
* `two hours thirty minutes ago`
|
||||
* ``an hour ago``
|
||||
* ``a minute ago``
|
||||
* ``50 min ago``
|
||||
* ``1h30m ago``
|
||||
* ``two hours thirty minutes ago``
|
||||
|
||||
Default formatters
|
||||
------------------
|
||||
|
|
@ -288,12 +172,26 @@ ways. Here's the full list.
|
|||
chart
|
||||
.....
|
||||
|
||||
(New in 1.4.0) Displays a nice chart of the weekly progress.
|
||||
(New in 1.4.0) Displays a nice chart of the weekly progress:
|
||||
|
||||
.. code:: text
|
||||
|
||||
Date Day Chart Hours
|
||||
|
||||
Sep 5 Mon ####### 3.8
|
||||
6 Tue #### 2.3
|
||||
7 Wed ####### 3.9
|
||||
8 Thu 0.0
|
||||
9 Fri ######### 4.5
|
||||
10 Sat ######### 4.7
|
||||
11 Sun 0.0
|
||||
|
||||
Week 19.3/20.0
|
||||
|
||||
**Settings**
|
||||
|
||||
By default this formatter will only display a nice chart of the progress divided
|
||||
by week and respecting the `week_start` setting. However you may specify a daily
|
||||
by week and respecting the ``week_start`` setting. However you may specify a daily
|
||||
goal and a weekly goal to customize the chart, as well as how many minutes each
|
||||
character represents:
|
||||
|
||||
|
|
@ -319,40 +217,92 @@ In yaml:
|
|||
text
|
||||
....
|
||||
|
||||
Displays nicely the entries grouped by sheet and day.
|
||||
Displays nicely the entries grouped by sheet and day. This is the default
|
||||
formatter. Pass ``-v`` to also reveal each entry's id:
|
||||
|
||||
.. code:: text
|
||||
|
||||
Timesheet: foo
|
||||
Day Start End Duration Notes
|
||||
Tue Sep 20, 2022 09:09:58 - 09:40:13 0:30:15 write tiempo's docs
|
||||
09:41:01 - 10:11:20 0:30:18 work on pizarra.categulario.xyz
|
||||
1:00:34
|
||||
-------------------------------------------------------------------------------------
|
||||
Total 1:00:34
|
||||
|
||||
ical
|
||||
....
|
||||
|
||||
This formatter's output can be redirected to a file and then uploaded to a
|
||||
calendar app.
|
||||
calendar app:
|
||||
|
||||
.. code:: text
|
||||
|
||||
BEGIN:VCALENDAR
|
||||
CALSCALE:GREGORIAN
|
||||
METHOD:PUBLISH
|
||||
PRODID:tiempo-rs
|
||||
VERSION:2.0
|
||||
BEGIN:VEVENT
|
||||
DESCRIPTION:write tiempo's docs
|
||||
DTEND:20220920T134013Z
|
||||
DTSTAMP:20220920T130958Z
|
||||
DTSTART:20220920T130958Z
|
||||
SEQUENCE:0
|
||||
SUMMARY:write tiempo's docs
|
||||
UID:tiempo-10@abraham-lenovo-t470s
|
||||
END:VEVENT
|
||||
BEGIN:VEVENT
|
||||
DESCRIPTION:work on pizarra.categulario.xyz
|
||||
DTEND:20220920T141120Z
|
||||
DTSTAMP:20220920T134101Z
|
||||
DTSTART:20220920T134101Z
|
||||
SEQUENCE:0
|
||||
SUMMARY:work on pizarra.categulario.xyz
|
||||
UID:tiempo-11@abraham-lenovo-t470s
|
||||
END:VEVENT
|
||||
END:VCALENDAR
|
||||
|
||||
csv
|
||||
...
|
||||
|
||||
Basically dump the entries as CSV to stdout. Useful for passing entries to a
|
||||
different tool.
|
||||
Dump the entries as CSV to stdout. Useful for passing entries to a different
|
||||
tool. Pass ``-v`` to add an ``id`` column.
|
||||
|
||||
.. code:: text
|
||||
|
||||
start,end,note,sheet
|
||||
2022-09-20T13:09:58.805280Z,2022-09-20T13:40:13.837994Z,write tiempo's docs,foo
|
||||
2022-09-20T13:41:01.478854Z,2022-09-20T14:11:20.461322Z,work on pizarra.categulario.xyz,foo
|
||||
|
||||
json
|
||||
....
|
||||
|
||||
Dump the entries in JSON format.
|
||||
Dump the entries in JSON format:
|
||||
|
||||
.. code:: json
|
||||
|
||||
[{"id":10,"note":"write tiempo's docs","start":"2022-09-20T13:09:58.805280283Z","end":"2022-09-20T13:40:13.837994932Z","sheet":"foo"},{"id":11,"note":"work on pizarra.categulario.xyz","start":"2022-09-20T13:41:01.478854071Z","end":"2022-09-20T14:11:20.461322041Z","sheet":"foo"}]
|
||||
|
||||
ids
|
||||
...
|
||||
|
||||
Dump only the ids in a single line
|
||||
Dump only the ids in a single line:
|
||||
|
||||
.. code:: text
|
||||
|
||||
2196 2197 2198 2199 2200 2201
|
||||
|
||||
Custom formatters
|
||||
-----------------
|
||||
|
||||
You can implement your own formatters for all subcommands that display entries
|
||||
(like `t display`, `t week` etc.). It is as easy as creating an executable file
|
||||
(like ``t display``, ``t week`` etc.). It is as easy as creating an executable file
|
||||
written in any programming language (interpreted or compiled) and placing it in
|
||||
a path listed in the config value for `formatter_search_paths`.
|
||||
a path listed in the config value for ``formatter_search_paths``.
|
||||
|
||||
This executable will be given as standard input a csv stream with each row
|
||||
representing a time entry with the same structure as the `csv` formatter output.
|
||||
representing a time entry with the same structure as the ``csv`` formatter output.
|
||||
It will also be given a command line argument representing user settings for
|
||||
this formatter stored in the config file and formatted as JSON.
|
||||
|
||||
|
|
@ -378,31 +328,31 @@ Suppose we have this config file:
|
|||
hourly_rate = 300
|
||||
currency = "USD"
|
||||
|
||||
then we can create the `earnings` formatter by placing the following file in
|
||||
`/home/user/.config/tiempo/formatters/earnings`:
|
||||
then we can create the ``earnings`` formatter by placing the following file in
|
||||
``/home/user/.config/tiempo/formatters/earnings`` and making it executable:
|
||||
|
||||
.. code:: python
|
||||
|
||||
#!/usr/bin/env python3
|
||||
import sys
|
||||
import json
|
||||
import csv
|
||||
from datetime import datetime, timezone
|
||||
from datetime import timedelta
|
||||
import sys, json, csv
|
||||
from datetime import datetime, timezone, timedelta
|
||||
from math import ceil
|
||||
|
||||
# Settings for this formatter passed as the first argument
|
||||
config = json.loads(sys.argv[1])
|
||||
|
||||
reader = csv.DictReader(
|
||||
sys.stdin,
|
||||
sys.stdin, # entries are received from stdin
|
||||
fieldnames=['id', 'start', 'end', 'note', 'sheet'],
|
||||
)
|
||||
|
||||
total = timedelta(seconds=0)
|
||||
|
||||
for line in reader:
|
||||
# times are formatted as ISO format
|
||||
start = datetime.strptime(line['start'], '%Y-%m-%dT%H:%M:%S.%fZ')
|
||||
|
||||
# entries that are still running don't have a value in the 'end' column
|
||||
if not line['end']:
|
||||
end = datetime.utcnow()
|
||||
else:
|
||||
|
|
@ -411,12 +361,13 @@ then we can create the `earnings` formatter by placing the following file in
|
|||
total += end - start
|
||||
|
||||
hours = total.total_seconds() / 3600
|
||||
# use the settings
|
||||
earnings = hours * config['hourly_rate']
|
||||
currency = config['currency']
|
||||
|
||||
print(f'You have earned: ${earnings:.2f} {currency}')
|
||||
|
||||
Now if you run `t display -f earnings` you will get something like:
|
||||
Now if you run ``t display -f earnings`` you will get something like:
|
||||
|
||||
.. code:: text
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue