From b515b0a31761d98af519728f49f503f9ca8a77c9 Mon Sep 17 00:00:00 2001
From: Abraham Toriz <categulario@gmail.com>
Date: Tue, 27 Sep 2022 22:47:54 -0400
Subject: [PATCH] document most settings

---
 docs/source/index.rst | 126 ++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 120 insertions(+), 6 deletions(-)

diff --git a/docs/source/index.rst b/docs/source/index.rst
index 4473e56..cc38e5a 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -251,6 +251,8 @@ the start time of the entry.
    The sheet to display. Pass 'all' to see entries from all sheets or 'full' to
    see hidden entries.
 
+.. _t-edit:
+
 t-edit
 ......
 
@@ -300,6 +302,8 @@ t-help
 Get help on the specified subcommand. It is equivalent to passing ``-h`` to any
 subcommand.
 
+.. _t-in:
+
 t-in
 ....
 
@@ -405,6 +409,8 @@ current time unless ``--at`` is passed, case in which the specified time is set
 as end time for the entry. See :ref:`specifying-times` to learn the accepted
 formats.
 
+.. _t-resume:
+
 t-resume
 ........
 
@@ -472,6 +478,8 @@ given time.
 
 Just like ``t-display`` this accepts ``--grep``, ``--ids``, and ``--format``.
 
+.. _t-week:
+
 t-week
 ......
 
@@ -498,25 +506,131 @@ Just like ``t-display`` this accepts ``--grep``, ``--ids``, and ``--format``.
 Settings
 --------
 
-.. note::
-
-   describe the settings file
+Tiempo settings are kept in a single ``TOML`` file. You can learn its location
+by running ``t c``. Here is the full list with descriptions.
 
 .. _append_notes_delimiter:
 
 append_notes_delimiter
 ......................
 
-.. _require_note:
+**Type**: string **Default**: ``" "``
 
-require_note
-............
+String used to concatenate text when ``--append`` is passed to :ref:`t-edit`.
+
+auto_checkout
+.............
+
+**Type**: bool **Default**: false
+
+Not implemented. Kept for compatibility with ``timetrap``. If you use it file an
+issue. Tracking issue https://gitlab.com/categulario/tiempo-rs/-/issues/11
+
+auto_sheet
+..........
+
+**Type**: string **Default**: ``"dotfiles"``
+
+Not implemented. Kept for compatibility with ``timetrap``. If you use it file an
+issue. Tracking issue: https://gitlab.com/categulario/tiempo-rs/-/issues/9
+
+auto_sheet_search_paths
+.......................
+
+**Type**: [string] **Default** Depends on OS, irrelevant anyways
+
+Not implemented. Kept for compatibility with ``timetrap``. If you use it file an
+issue. Tracking issue: https://gitlab.com/categulario/tiempo-rs/-/issues/9
+
+commands
+........
+
+**Type**: CommandsSettings,
+
+database_file
+.............
+
+**Type**: string **Default** Depends on OS
+
+Absolute path to the database file.
+
+default_command
+...............
+
+**Type**: string|null **Default**: null
+
+Not implemented. Kept for compatibility with ``timetrap``. Implementation
+planned. Tracking issue: https://gitlab.com/categulario/tiempo-rs/-/issues/10
+
+default_formatter
+.................
+
+**Type**: string **Default**: ``"text"``
+
+Formatter used for the :ref:`t-display` family of commands when no ``--format``
+argument is passed. Included formatters are explained in the
+:ref:`default-formatters` section, they are: chart, text, ical, csv, json, ids.
+
+formatter_search_paths
+......................
+
+**Type**: [string] **Default**: Depends on OS, but not empty
+
+Array of paths to search for custom formatters. See :ref:`custom-formatters` to
+learn how to write them. Custom formatters must be executable files.
+
+formatters
+..........
+
+**Type**: FormattersSettings,
 
 .. _interactive_entries:
 
 interactive_entries
 ...................
 
+**Type**: integer **Default** 10
+
+Number of unique entries to show when interactive commands like :ref:`t-resume`
+are invoked.
+
+.. _note_editor:
+
+note_editor
+...........
+
+**Type**: string|null **Default** ``null``
+
+Specify an editor to use when starting an entry without a note and when
+:ref:`require_note` is true. By default ``tiempo`` respects the ``$EDITOR``
+variable so you can leave this setting as ``null`` most of the time.
+
+.. _require_note:
+
+require_note
+............
+
+**Type**: bool **Default** true
+
+Wether or not entries require a note to be recorded. If true then running
+:ref:`t-in` without arguments will launch the text editor configured in
+:ref:`note_editor`
+
+round_in_seconds
+................
+
+**Type**: integer **Default**: 900 (15 min)
+
+Not implemented, kept for compatibility with timetrap. Tracking issue:
+https://gitlab.com/categulario/tiempo-rs/-/issues/6
+
+week_start
+..........
+
+**Type**: string **Default** ``"monday"``
+
+Day of the week that should be considered as the start for :ref:`t-week`.
+
 Per command default formatters
 ..............................