Trevor Caira avatar Trevor Caira committed 316658b

Added install and readme documentation.

Comments (0)

Files changed (3)

+Installation
+============
+
+To install timebook, run the following command from the mercurial
+repository::
+
+    python setup.py install
+
+This will install timebook to the default location on your system. To
+install to a different directory, supply setup.py with the ``--prefix``
+option. For details, refer to ``python setup.py install --help`` and the
+python setuptools documentation.
+
+Alternatively, you can copy or symlink the ``timebook`` subdirectory to
+a directory on your python path, and copy or symlink the ``t``
+executable to a directory on your ``PATH``. This facilitates updating
+through mercurial.
+Timebook
+========
+
+Timebook is a small utility which aims to be a low-overhead way of
+tracking what you spend time on. It can be used to prepare annotated
+time logs of work for presentation to a client, or simply track how you
+spend your free time. Timebook is implemented as a python script which
+maintains its state in a sqlite3 database.
+
+Concepts
+~~~~~~~~
+
+Timebook maintains a list of *timesheets* -- distinct lists timed
+*periods*. Each period has a start and end time, with the exception of the
+most recent period, which may have no end time set. This indicates that
+this period is still running. Timesheets containing such periods are
+considered *active*. It is possible to have multiple timesheets active
+simultaneously, though a single time sheet may only have one period
+running at once.
+
+Interactions with timebook are performed through the ``t`` command on
+the command line. ``t`` is followed by one of timebook's subcommands.
+Often used subcommands include ``start``, ``stop``, ``switch``,
+``info``, ``list`` and ``show``. Commands may be abbreviated as long as
+they are unambiguous: thus ``t switch foo`` and ``t sw foo`` are
+identical. Likewise, commands which display timesheets accept
+abbreviated timesheet names. ``t show f`` is thus equivalent to ``t show
+foo`` if ``foo`` is the only timesheet which begins with "f". Note that
+this does not apply to ``t switch``, since this command also creates
+timesheets. (Using the earlier example, if ``t switch f`` is entered, it
+would thus be ambiguous whether a new timesheet ``f`` or switching to
+the existing timesheet ``foo`` was desired).
+
+Usage
+~~~~~
+
+The basic usage is as follows::
+
+  $ t switch writing
+  $ t start document timebook
+  $ t stop
+
+The first command, ``t switch writing``, switches to the timesheet
+"writing" (or creates it if it does not exist). ``t start document
+timebook`` creates a new period in the current timesheet, and annotates
+it with the description "document timebook". Note that this command
+would be in error if the ``writing`` timesheet was already active.
+Finally, ``t stop`` records the current time as the end time for the
+most recent period in the ``writing`` timesheet.
+
+To display the current timesheet, invoke the ``t show`` command::
+
+  $ t show
+  Timesheet writing:
+  Day            Start      End        Duration   Notes
+  Mar 14, 2009   19:53:30 - 20:06:15   0:12:45    document timebook
+                 20:07:02 -            0:00:01    write home about timebook
+                                       0:12:46
+  Total                                0:12:46
+
+Each period in the timesheet is listed on a row. If the timesheet is
+active, the final period in the timesheet will have no end time. After
+each day, the total time tracked in the timesheet for that day is
+listed. Note that this is computed by summing the durations of the
+periods beginning in the day. In the last row, the total time tracked in
+the timesheet is shown.
+
+To get a complete listing of commands, see the output of ``t --help``.
     name='timebook',
     version='.'.join(str(bit) for bit in __version__),
     url='http://bitbucket.org/trevor/timebook/',
-    description='Simple time tracking utility',
+    description='track what you spend time on',
     author='Trevor Caira',
     author_email='trevor@caira.com',
     classifiers=[
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.