From 8b4f34538762ed6d9aa7f7bbd8221251af0634d0 Mon Sep 17 00:00:00 2001 From: "Dustin J. Mitchell" Date: Fri, 1 Jan 2021 21:17:42 +0000 Subject: [PATCH] Update documentation for reports, new CLI This is basically a redraft of the documentation to be more complete and better cover some of the features added since it was written. --- cli/src/invocation/mod.rs | 4 +- docs/src/SUMMARY.md | 7 ++- docs/src/config-file.md | 42 +++++++++++++++++ docs/src/debugging.md | 9 ++++ docs/src/reports.md | 81 +++++++++++++++++++++++++++++++++ docs/src/running-sync-server.md | 8 ++++ docs/src/task-sync.md | 23 ++++++++++ docs/src/usage.md | 75 ------------------------------ docs/src/using-task-command.md | 9 ++++ docs/src/welcome.md | 16 ++++--- 10 files changed, 189 insertions(+), 85 deletions(-) create mode 100644 docs/src/config-file.md create mode 100644 docs/src/debugging.md create mode 100644 docs/src/reports.md create mode 100644 docs/src/running-sync-server.md create mode 100644 docs/src/task-sync.md delete mode 100644 docs/src/usage.md create mode 100644 docs/src/using-task-command.md diff --git a/cli/src/invocation/mod.rs b/cli/src/invocation/mod.rs index 3d5a953dc..16c9b0374 100644 --- a/cli/src/invocation/mod.rs +++ b/cli/src/invocation/mod.rs @@ -110,10 +110,10 @@ fn get_replica(settings: &Config) -> Fallible { /// Get the server for this invocation fn get_server(settings: &Config) -> Fallible> { - // if server_client_id and server_origin are both set, use + // if server_client_key and server_origin are both set, use // the remote server if let (Ok(client_key), Ok(origin)) = ( - settings.get_str("server_client_id"), + settings.get_str("server_client_key"), settings.get_str("server_origin"), ) { let client_key = Uuid::parse_str(&client_key)?; diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md index 40871f638..c8f56bdc6 100644 --- a/docs/src/SUMMARY.md +++ b/docs/src/SUMMARY.md @@ -2,7 +2,12 @@ - [Welcome to TaskChampion](./welcome.md) - [Installation](./installation.md) - - [Usage](./usage.md) + * [Using the Task Command](./using-task-command.md) + * [Configuration](./config-file.md) + * [Reports](./reports.md) + * [Synchronization](./task-sync.md) + * [Running the Sync Server](./running-sync-server.md) + * [Debugging](./debugging.md) - [Internal Details](./internals.md) - [Data Model](./data-model.md) - [Replica Storage](./storage.md) diff --git a/docs/src/config-file.md b/docs/src/config-file.md new file mode 100644 index 000000000..74737b98c --- /dev/null +++ b/docs/src/config-file.md @@ -0,0 +1,42 @@ +# Configuration + +The `task` command will work out-of-the-box with no configuration file, using default values. + +Configuration is read from `taskchampion.yaml` in your config directory. +On Linux systems, that directory is `~/.config`. +On OS X, it's `~/Library/Preferences`. +On Windows, it's `AppData/Roaming` in your home directory. +The path can be overridden by setting `$TASKCHAMPION_CONFIG`. + +Individual configuration parameters can be overridden by environment variables, converted to upper-case and prefixed with `TASKCHAMPION_`, e.g., `TASKCHAMPION_DATA_DIR`. +Nested configuration parameters such as `reports` cannot be overridden by environment variables. + +## Directories + +* `data_dir` - path to a directory containing the replica's task data (which will be created if necessary). + Default: `taskchampion` in the local data directory. + +## Sync Server + +If using a local server: + +* `server_dir` - path to a directory containing the local server's data. + This is only used if `server_origin` or `server_client_key` are not set. + Default: `taskchampion-sync-server` in the local data directory. + +If using a remote server: + +* `server_origin` - Origin of the TaskChampion sync server, e.g., `https://taskchampion.example.com`. + If not set, then sync is done to a local server. +* `encryption_secret` - Secret value used to encrypt all data stored on the server. + This should be a long random string. + If you have `openssl` installed, a command like `openssl rand -hex 35` will generate a suitable value. + This value is only used when synchronizing with a remote server -- local servers are unencrypted. + Treat this value as a password. +* `server_client_key` - Client key to identify this replica to the sync server (a UUID) + If not set, then sync is done to a local server. + +# Reports + +* `reports` - a mapping of each report's name to its definition. + See [Reports](./reports.md) for details. diff --git a/docs/src/debugging.md b/docs/src/debugging.md new file mode 100644 index 000000000..f3de1c7a7 --- /dev/null +++ b/docs/src/debugging.md @@ -0,0 +1,9 @@ +# Debugging + +Both `task` and `taskchampion-sync-server` use [env-logger](https://docs.rs/env_logger) and can be configured to log at various levels with the `RUST_LOG` environment variable. +For example: +```shell +$ RUST_LOG=taskchampion=trace task add foo +``` + +The output may provide valuable clues in debugging problems. diff --git a/docs/src/reports.md b/docs/src/reports.md new file mode 100644 index 000000000..376bf3531 --- /dev/null +++ b/docs/src/reports.md @@ -0,0 +1,81 @@ +# Reports + +As a to-do list manager, listing tasks is an important TaskChampion feature. +Reports are tabular displays of tasks, and allow very flexible filtering, sorting, and customization of columns. + +TaskChampion includes several "built-in" reports, as well as supporting custom reports in the [configuration file](./config-file.md). + +## Built-In Reports + +The `next` report is the default, and lists all pending tasks: + +```text +$ task +Id Description Active Tags +1 learn about TaskChampion +next +2 buy wedding gift * +buy +``` + +The `Id` column contains short numeric IDs that are assigned to pending tasks. +These IDs are easy to type, such as to mark task 2 done (`task 2 done`). + +The `list` report lists all tasks, with a similar set of columns. + +## Custom Reports + +Custom reports are defined in the configuration file's `reports` property. +This is a mapping from each report's name to its definition. +Each definition has the following properties: + +* `filter` - criteria for the tasks to include in the report +* `sort` - how to order the tasks +* `columns` - the columns of information to display for each task + +The filter is a list of filter arguments, just like those that can be used on the command line. +See the `task help` output for more details on this syntax. +For example: + +```yaml +reports: + garden: + filter: + - "status:pending" + - "+garden" +``` + +The sort order is defined by an array of objects containing a `sort_by` property and an optional `ascending` property. +Tasks are compared by the first criterion, and if that is equal by the second, and so on. +For example: + +```yaml +reports: + garden: + sort: + - sort_by: description + - sort_by: uuid + ascending: false +``` +If `ascending` is given, it can be `true` for the default sort order, or `false` for the reverse. + +The available values of `sort_by` are + +(TODO: generate automatically) + +Finally, the configuration specifies the list of columns to display in the `columns` property. +Each element has a `label` and a `property`: + +```yaml +reports: + garden: + columns: + - label: Id + property: id + - label: Description + property: description + - label: Tags + property: tags +``` + +The avaliable properties are: + +(TODO: generate automatically) diff --git a/docs/src/running-sync-server.md b/docs/src/running-sync-server.md new file mode 100644 index 000000000..2cc3b7454 --- /dev/null +++ b/docs/src/running-sync-server.md @@ -0,0 +1,8 @@ +# Running the Sync Server + +> NOTE: TaskChampion is still in development and not yet feature-complete. +> The server is functional, but lacks any administrative features. + +Run `taskchampion-sync-server` to start the sync server. +Use `--port` to specify the port it should listen on, and `--data-dir` to specify the directory which it should store its data. +It only serves HTTP; the expectation is that a frontend proxy will be used for HTTPS support. diff --git a/docs/src/task-sync.md b/docs/src/task-sync.md new file mode 100644 index 000000000..7d874760c --- /dev/null +++ b/docs/src/task-sync.md @@ -0,0 +1,23 @@ +# Synchronization + +A single TaskChampion task database is known as a "replica". +A replica "synchronizes" its local information with other replicas via a sync server. +Many replicas can thus share the same task history. + +This operation is triggered by running `task sync`. +Typically this runs frequently in a cron task. +Synchronization is quick, especially if no changes have occurred. + +Each replica expects to be synchronized frequently, even if no server is involved. +Without periodic syncs, the storage space used for the task database will grow quickly, and performance will suffer. + +By default, TaskChampion syncs to a "local server", as specified by the `server_dir` configuration parameter. +Every replica sharing a task history should have precisely the same configuration for `server_origin`, `server_client_key`, and `encryption_secret`. + +Synchronizing a new replica to an existing task history is easy: begin with an empty replica, configured for the remote server, and run `task sync`. +The replica will download the entire task history. + +It is possible to switch a single replica to a remote server by simply configuring for the remote server and running `task sync`. +The replica will upload the entire task history to the server. +Once this is complete, additional replicas can be configured with the same settings in order to share the task history. + diff --git a/docs/src/usage.md b/docs/src/usage.md deleted file mode 100644 index 39cf18bf7..000000000 --- a/docs/src/usage.md +++ /dev/null @@ -1,75 +0,0 @@ -# Usage - -## `task` - -The main interface to your tasks is the `task` command, which supports various subcommands. -You can find a quick list of all subcommands with `task help`. - -Note that the `task` interface does not match that of TaskWarrior. - -### Configuration - -The `task` command will work out-of-the-box with no configuration file, using default values. - -Configuration is read from `taskchampion.yaml` in your config directory. -On Linux systems, that directory is `~/.config`. -On OS X, it's `~/Library/Preferences`. -On Windows, it's `AppData/Roaming` in your home directory. -The path can be overridden by setting `$TASKCHAMPION_CONFIG`. - -Individual configuration parameters can be overridden by environment variables, converted to upper-case and prefixed with `TASKCHAMPION_`, e.g., `TASKCHAMPION_DATA_DIR`. -Nested configuration parameters cannot be overridden by environment variables. - -The following configuration parameters are available: - -* `data_dir` - path to a directory containing the replica's task data (which will be created if necessary). - Default: `taskchampion` in the local data directory. -* `server_dir` - path to a directory containing the local server's data. - This is only used if `server_origin` or `server_client_id` are not set. - Default: `taskchampion-sync-server` in the local data directory. -* `encryption_secret` - Secret value used to encrypt all data stored on the server. - This should be a long random string. - If you have `openssl` installed, a command like `openssl rand -hex 35` will generate a suitable value. - This value is only used when synchronizing with a remote server -- local servers are unencrypted. - Treat this value as a password. -* `server_origin` - Origin of the TaskChampion sync server, e.g., `https://taskchampion.example.com`. - If not set, then sync is done to a local server. -* `server_client_id` - Client ID to identify this replica to the sync server (a UUID) - If not set, then sync is done to a local server. - -### Synchronization - -A single TaskChampion task database is known as a "replica". -A replica "synchronizes" its local information with other replicas via a sync server. -Many replicas can thus share the same task history. - -This operation is triggered by running `task sync`. -Typically this runs frequently in a cron task. -Synchronization is quick, especially if no changes have occurred. - -Each replica expects to be synchronized frequently, even if no server is involved. -Without periodic syncs, the storage space used for the task database will grow quickly, and performance will suffer. - -By default, TaskChampion syncs to a "local server", as specified by the `server_dir` configuration parameter. -Every replica sharing a task history should have precisely the same configuration for `server_origin`, `server_client_id`, and `encryption_secret`. - -Synchronizing a new replica to an existing task history is easy: begin with an empty replica, configured for the remote server, and run `task sync`. -The replica will download the entire task history. - -It is possible to switch a single replica to a remote server by simply configuring for the remote server and running `task sync`. -The replica will upload the entire task history to the server. -Once this is complete, additional replicas can be configured with the same settings in order to share the task history. - -## `taskchampion-sync-server` - -Run `taskchampion-sync-server` to start the sync server. -Use `--port` to specify the port it should listen on, and `--data-dir` to specify the directory which it should store its data. -It only serves HTTP; the expectation is that a frontend proxy will be used for HTTPS support. - -## Debugging - -Both `task` and `taskchampio-sync-server` use [env-logger](https://docs.rs/env_logger) and can be configured to log at various levels with the `RUST_LOG` environment variable. -For example: -```shell -$ RUST_LOG=taskchampion=trace task add foo -``` diff --git a/docs/src/using-task-command.md b/docs/src/using-task-command.md new file mode 100644 index 000000000..dcc57b6f5 --- /dev/null +++ b/docs/src/using-task-command.md @@ -0,0 +1,9 @@ +# Using the Task Command + +The main interface to your tasks is the `task` command, which supports various subcommands such as `add`, `modify`, `start`, and `done`. +Customizable [reports](./reports.md) are also available as subcommands, such as `next`. +The command reads a [configuration file](./config-file.md) for its settings, including where to find the task database. +And the `sync` subcommand [synchronizes tasks with a sync server](./task-sync.md). +You can find a list of all subcommands, as well as the built-in reports, with `task help`. + +> NOTE: the `task` interface does not precisely match that of TaskWarrior. diff --git a/docs/src/welcome.md b/docs/src/welcome.md index c0e45c16a..a650c543a 100644 --- a/docs/src/welcome.md +++ b/docs/src/welcome.md @@ -3,7 +3,7 @@ TaskChampion is a personal task-tracking tool. It works from the command line, with simple commands like `task add "fix the kitchen sink"`. It can synchronize tasks on multiple devices, and does so in an "offline" mode so you can update your tasks even when you can't reach the server. -If you've heard of [TaskWarrior](https://taskwarrior.org/), this tool is very similar, but actively maintained and with a more reliable synchronization system. +If you've heard of [TaskWarrior](https://taskwarrior.org/), this tool is very similar, but with some different design choices and greater reliability. ## Getting Started @@ -14,16 +14,16 @@ Once you've [installed TaskChampion](./installation.md), your interface will be Start by adding a task: ```shell -$ task add "learn how to use taskchampion" +$ task add learn how to use taskchampion added task ba57deaf-f97b-4e9c-b9ab-04bc1ecb22b8 ``` -You can see all of your pending tasks with `task pending`, or just `task` for short: +You can see all of your pending tasks with `task next`, or just `task` for short: ```shell $ task - id act description - 1 learn how to use taskchampion + Id Description Active Tags + 1 learn how to use taskchampion ``` Tell TaskChampion you're working on the task, using the shorthand id: @@ -49,13 +49,15 @@ $ task sync Typically sync is run from a crontab, on whatever schedule fits your needs. -To synchronize multiple replicas of your tasks, you will need a sync server and a client ID on that server. +To synchronize multiple replicas of your tasks, you will need a sync server and a client key for that server. Configure these in `~/.config/taskchampion.yml`, for example: ```yaml -server_client_id: "f8d4d09d-f6c7-4dd2-ab50-634ed20a3ff2" +server_client_key: "f8d4d09d-f6c7-4dd2-ab50-634ed20a3ff2" server_origin: "https://taskchampion.example.com" ``` The next run of `task sync` will upload your task history to that server. Configuring another device identically and running `task sync` will download that task history, and continue to stay in sync with subsequent runs of the command. + +See [Usage](./usage.md) for more detailed information on using TaskChampion.