From 49e068c5a316f9989e6f5c899dc2a5d0e0e295ae Mon Sep 17 00:00:00 2001
From: Abraham Toriz <categulario@gmail.com>
Date: Sun, 25 Sep 2022 18:14:06 -0400
Subject: [PATCH] more docs for some commands

---
 docs/source/index.rst | 225 ++++++++++++++++++++++++++++++++++++++++--
 src/main.rs           |   5 +-
 2 files changed, 222 insertions(+), 8 deletions(-)

diff --git a/docs/source/index.rst b/docs/source/index.rst
index f849105..8201ade 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -87,17 +87,226 @@ Tutorial
 
    yo, doc this
 
-Commands
---------
+Subcommands
+-----------
 
-.. note::
+t-archive
+.........
 
-   TODO finish this
+``t a|archive [OPTIONS] [SHEET]``
 
-t-in
+By default this command will ask for you confirmation, then archive ALL entries
+in the current timesheet. Pass ``--fake`` to only display the entries using the
+``text`` formatter (useful if you want to make sure that the archived
+time/entries are correct).
+
+Using ``--start`` and ``--end`` you can further limit the period of time that
+will be archived (See **Specifying times** section of the docs on the accepted
+formats). You can use ``--grep`` to only archive certain entries that match the
+given regular expression.
+
+If what you need is to archive a specific elapsed time, for example only 15
+hours out of however many the timesheet has use ``--time`` with the amount of
+hours you want to archive.
+
+**Options**
+
+-f, --fake
+   Don't actually archive the entries, just display them
+
+-e, --end <TIME>
+   Include entries that start on this date or earlier
+
+-g, --grep <REGEXP>
+   Include entries where the note matches this regexp.
+
+-s, --start <TIME>
+   Include entries that start on this date or later
+
+-t, --time <HOURS>
+   Time in hours to archive. Archived time will be equal or less than this.
+
+``SHEET``
+   Archive entries from this timesheet instead of the current one.
+
+t-backend
+.........
+
+``t b|backend``
+
+Open a sqlite3 shell into the database. Sqlite3 must be installed  and in the
+``PATH`` variable for this command to work.
+
+t-configure
+...........
+
+``t c|configure [OPTIONS]``
+
+If called without arguments ``t c`` will print the absoulte path to the config
+file. If you pass arguments they'll be used to edit your config file in place.
+
+.. warning::
+
+   This will erase any comments you might have added to your toml or yaml file.
+   It is better to edit the config file manually with your preferred text
+   editor:
+
+   .. code:: shell-session
+
+      vim $(t c)
+
+**Options**
+
+--auto-checkout
+   Checkout of current running entry when starting a new one. **Not
+   implemented**.
+
+--no-auto-checkout
+   Starting a new entry fails if one is running (default).
+
+--no-require-note
+   Entries can be created without a note.
+
+--require-note
+   Prompt for a note if one isn't provided when checking in (default).
+
+--append-notes-delimiter <DELIMITER>
+   delimiter used when appending notes via t edit --append. Default: ' '
+   (space).
+
+--database-file <PATH>
+   Set the absoulte path to the sqlite database. A new database will be created
+   at this location if one does not exist.
+
+--default-formatter <FORMATTER>
+   The format to use when display commands are invoked without a ``--format``
+   option. Defaults to ``'text'``. See **Settings** section of the docs for
+   per-command default formatter.
+
+``--formatter-search-paths <PATH>[,<PATH>...]``
+   comma separated paths to search for user defined fomatters. See **Custom
+   formatters** section for more info on this.
+
+--interactive-entries <N>
+   How many unique previous notes to show when selecting interactively. An
+   example of an interactive command is ``t resume -i``.
+
+--note-editor <EDITOR>
+   Specify a custom command used to edit an entry's note. Default: $EDITOR
+
+--round-in-seconds <SECONDS>
+   The duration of time to use for rounding with the -r flag. Default: 900 (15
+   m). **Not implemented**.
+
+--week-start <DAY>
+   The day of the week to use as the start of the week for t week. Default:
+   monday [possible values: monday, tuesday, wednesday, thursday, friday,
+   saturday, sunday]
+
+.. _t-display:
+
+t-display
+.........
+
+``t d|display [OPTIONS] [SHEET|all|full]``
+
+Display all entries in the current timesheet using the specified formatter (by
+default this is ``text``). For more information on formatters see
+:ref:`default-formatters`. For information on custom formatters see
+:ref:`custom-formatters`.
+
+It is worh noting that **BOTH** the ``--start`` and ``--end`` arguments act on
+the start time of the entry.
+
+**Options**
+
+-v, --ids
+   Print database ids (for use with edit).
+
+-e, --end <TIME>
+   Include entries that start on this date or earlier.
+
+-f, --format <FORMAT>
+   The output format. Valid built-in formats are chart, text, ical, csv, json
+   and ids. See :ref:`default-formatters` for more info. See
+   :ref:`custom-formatters` to learn how to make your own.
+
+-g, --grep <REGEXP>
+   Only display entries whose notes match this regular expression.
+
+-s, --start <TIME>
+   Include entries that start on this date or later.
+
+``<SHEET>``
+   The sheet to display. Pass 'all' to see entries from all sheets or 'full' to
+   see hidden entries.
+
+edit
 ....
 
-login
+help
+....
+
+in
+..
+
+kill
+....
+
+list
+....
+
+t-month
+.......
+
+``t m|month [OPTIONS] [SHEET|all|full]``
+
+Like :ref:`t-display` but only display entries that started this month in the
+current timezone. Pass ``--month MONTH`` to display entries of different months.
+
+Just like ``t-display`` this accepts ``--grep``, ``--ids``, and ``--format``.
+
+now
+...
+
+out
+...
+
+resume
+......
+
+sheet
+.....
+
+t-today
+.......
+
+``t t|today [OPTIONS] [SHEET|all|full]``
+
+Like :ref:`t-display` but only display entries that started this month in the
+current timezone. Pass ``--month MONTH`` to display entries of different months.
+
+Just like ``t-display`` this accepts ``--grep``, ``--ids``, and ``--format``.
+
+t-week
+......
+
+``t w|week [OPTIONS] [SHEET|all|full]``
+
+Like :ref:`t-display` but only display entries that started this month in the
+current timezone. Pass ``--month MONTH`` to display entries of different months.
+
+Just like ``t-display`` this accepts ``--grep``, ``--ids``, and ``--format``.
+
+t-yesterday
+...........
+
+``t y|yesterday [OPTIONS] [SHEET|all|full]``
+
+Like :ref:`t-display` but only display entries that started this month in the
+current timezone. Pass ``--month MONTH`` to display entries of different months.
+
+Just like ``t-display`` this accepts ``--grep``, ``--ids``, and ``--format``.
 
 Settings
 --------
@@ -180,6 +389,8 @@ day in the computer's timezone. Add ``Z`` or an offset to specify the timezone.
 * ``1h30m ago``
 * ``two hours thirty minutes ago``
 
+.. _default-formatters:
+
 Default formatters
 ------------------
 
@@ -310,6 +521,8 @@ Dump only the ids in a single line:
 
    2196 2197 2198 2199 2200 2201
 
+.. _custom-formatters:
+
 Custom formatters
 -----------------
 
diff --git a/src/main.rs b/src/main.rs
index 2c56025..5b4f3fc 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -98,7 +98,7 @@ fn main() {
     let grep_arg = Arg::with_name("grep")
         .long("grep").short("g")
         .takes_value(true).value_name("REGEXP")
-        .help("Include entries where the note matches this regexp.");
+        .help("Only include entries whose note matches this regular expression");
 
     let format_arg = Arg::with_name("format")
         .short("f").long("format")
@@ -106,7 +106,8 @@ fn main() {
         .help(
             "The output format. Valid built-in formats are chart, text, ical, \
             csv, json and ids. Documentation on defining custom formats can be \
-            found at https://gitlab.com/categulario/tiempo"
+            found at https://tiempo.categulario.xyz or the man page included \
+            with the installation."
         );
 
     let sheet_arg = Arg::with_name("sheet")