diff options
| -rw-r--r-- | .gitignore | 1 | ||||
| -rw-r--r-- | README.markdown | 8 | ||||
| -rw-r--r-- | Rakefile | 13 | ||||
| -rw-r--r-- | man/hcl.1.ronn | 176 |
4 files changed, 19 insertions, 179 deletions
@@ -9,3 +9,4 @@ doc coverage test/dot_hcl *.1 +man/hcl.1.ronn diff --git a/README.markdown b/README.markdown index e819bfd..0e11288 100644 --- a/README.markdown +++ b/README.markdown @@ -11,7 +11,7 @@ HCl is a command-line tool for interacting with Harvest time sheets using the [htt]: http://www.getharvest.com/api/time_tracking [rdoc]: http://rdoc.info/github/zenhob/hcl/file/README.markdown -## Quick Start +## GETTING STARTED You can install hcl directly from rubygems.org: @@ -21,7 +21,7 @@ or you can install from source: rake install -## Usage +## SYNOPSIS hcl [start] @<task_alias> [+<time>] [<message>] hcl note <message> @@ -37,6 +37,8 @@ or you can install from source: hcl config hcl status +## DESCRIPTION + ### Available Projects and Tasks To start a new timer you need to identify the project and task. @@ -184,7 +186,7 @@ current response time, along with a timestamp of when it was last tested. [status API]: http://harveststatus.com/status_api -## Author +## AUTHOR HCl was designed and implemented by [Zack Hobson][zgh]. @@ -10,15 +10,28 @@ Rake::TestTask.new do |t| end task :default => :test +# process the README into a manual page using ronn require 'ronn' task :man do print "Writing manual page..." + readme = File.read('README.markdown') + head, content = readme.split("## SYNOPSIS\n") + content.prepend <<-END +hcl(1) -- Track time with Harvest time sheets +============================================= + +## SYNOPSIS + END + FileUtils.mkdir_p('man') + File.write('man/hcl.1.ronn', content) File.open('man/hcl.1','w').tap do |man| man.write Ronn::Document.new('man/hcl.1.ronn').to_roff end puts "done." end task 'build:gem' => [:man] +task 'install' => [:man] +task 'release' => [:man] require 'yard' YARD::Rake::YardocTask.new diff --git a/man/hcl.1.ronn b/man/hcl.1.ronn deleted file mode 100644 index 22756a0..0000000 --- a/man/hcl.1.ronn +++ /dev/null @@ -1,176 +0,0 @@ -hcl(1) -- Track time with Harvest time sheets -============================================= - -## SYNOPSIS - - hcl [start] @<task_alias> [+<time>] [<message>] - hcl note <message> - hcl stop [<message>] - hcl resume [@<task_alias>] - hcl log @<task_alias> [+<time>] [<message>] - hcl show [<date>] - hcl tasks [<project_code>] - hcl alias <task_alias> <project_id> <task_id> - hcl unalias <task_alias> - hcl aliases - hcl (cancel | nvm | oops) - hcl config - hcl status - -## DESCRIPTION - -HCl is a command-line tool for interacting with Harvest time sheets using the -Harvest time tracking API. - -### Available Projects and Tasks - -To start a new timer you need to identify the project and task. -The tasks command displays a list of available tasks with their -project and task IDs. - - hcl tasks - -You can also pass a project code (this is the short optional code associated -with each project) to list only the tasks for that project. - -### Starting a Timer - -Since it's not practical to enter two long numbers every time you want to -identify a task, HCl supports task aliases: - - hcl alias tacodev 1234 5678 - hcl @tacodev Adding a new feature - -### Starting a Timer with Initial Time - -You can also provide an initial time when starting a new timer. -This can be expressed in floating-point or HH:MM. The following two -commands are equivalent: - - hcl @tacodev +0:15 Doing some stuff - hcl +.25 @tacodev Doing some stuff - -### Adding Notes to a Running Task - -While a task is running you can append lines to the task notes: - - hcl note Then I did something else - -**Note** that `show` only displays the last line of the timer notes. -You can list all the notes for a running timer by issuing the note -command without any arguments: - - hcl note - -### Stopping a Timer - -The following command will stop a running timer (currently only one timer at -a time is supported). You can provide a message when stopping a timer as -well: - - hcl stop All done doing things - -### Resuming a Timer - -You can resume a stopped timer. Specify a task to resume the last timer -for that task: - - hcl resume - hcl resume @xdev - -### Canceling a Timer - -If you accidentally started a timer that you didn't mean to, you can cancel -it: - - hcl cancel - -This will delete the running timer, or the last-updated timer if one isn't -running. You can also use `nvm` or `oops` instead of `cancel`. - -### Logging without Starting a Timer - -You can log time and notes without leaving a timer running. It takes -the same arguments as start: - - hcl log @xdev +1 Worked for an hour. - -The above starts and immediately stops a one-hour timer with the given note. - -## ADVANCED USAGE - -### Bash Auto-completion of Task Aliases - -You can enable auto-completion of task aliases by adding this to your shell -configuration: - - complete -W "`cat ~/.hcl/aliases`" hcl - -### Configuration Profiles - -You can modify your credentials with the `--reauth` option, and review them -with `hcl config`. If you'd rather store multiple configurations at -once, specify an alternate configuration directory in the environment as -`HCL_DIR`. This can be used to interact with multiple harvest accounts at -once. - -Here is a shell alias `myhcl` with a separate configuration from the -main `hcl` command, and another command to configure alias completion: - - alias myhcl="env HCL_DIR=~/.myhcl hcl" - complete -W "`cat ~/.myhcl/aliases`" myhcl - -Adding something like the above to your bashrc will enable a new command, -`myhcl`. When using `myhcl` you can use different credentials and aliases, -while `hcl` will continue to function with your original configuration. - -### Interactive Console - -An interactive Ruby console is provided to allow you to use the fairly -powerful Harvest API client built into HCl, since not all of its -features are exposed via the command line. The current {HCl::App} -instance is available as `hcl`. - -It's also possible to issue HCl commands directly (except `alias`, see -below), or to query specific JSON end points and have the results -pretty-printed: - - hcl console - hcl> show "yesterday" - # => prints yesterday's timesheet, note the quotes! - hcl> hcl.http.get('daily') - # => displays a pretty-printed version of the JSON output - -Note that the HCl internals may change without notice. -Also, commands (like `alias`) that are also reserved words in Ruby -can't be issued directly (use `send :alias` instead). - -### Date Formats - -Dates can be expressed in a variety of ways. See the [Chronic documentation][cd] -for more information about available date input formats. The following -commands show the time sheet for the specified day: - - hcl show yesterday - hcl show last friday - hcl show 2 days ago - hcl show 1 week ago - -[cd]: http://chronic.rubyforge.org/ - -### Harvest service status - -Harvest provides a [status API], which you can query using the -`hcl status` command. This will tell you whether Harvest itself is up and the -current response time, along with a timestamp of when it was last tested. - -[status API]: http://harveststatus.com/status_api - -## AUTHOR - -HCl was designed and implemented by Zack Hobson. - -* Non-SSL support by Michael Bleigh. -* Resume command by Brian Cooke. -* UI improvements by Chris Scharf. - |