diff --git a/rust/README.md b/rust/README.md index bc076c792..e9309e2a8 100644 --- a/rust/README.md +++ b/rust/README.md @@ -50,9 +50,3 @@ NOTE: on Windows, the "BCrypt" library must be included when linking to taskcham ### As a Rust dependency If you would prefer to build Taskchampion directly into your project, and have a build system capable of building Rust libraries (such as CMake), the `taskchampion-lib` crate can be referenced as an `rlib` dependency. - -## Documentation Generation - -The `mdbook` configuration contains a "preprocessor" implemented in the `taskchampion-cli` crate in order to reflect CLI usage information into the generated book. -This preprocessor is not built by default. -To (re)build it, run `cargo build -p taskchampion-cli --features usage-docs --bin usage-docs`. diff --git a/rust/build-docs.sh b/rust/build-docs.sh index f693349c7..c7ceb734e 100755 --- a/rust/build-docs.sh +++ b/rust/build-docs.sh @@ -11,9 +11,6 @@ if ! [ -f "docs/src/SUMMARY.md" ]; then exit 1 fi -# build the latest version of the mdbook plugin -cargo build -p taskchampion-cli --features usage-docs --bin usage-docs - # create a worktree of this repo, with the `gh-pages` branch checked out git branch -f gh-pages $REMOTE/gh-pages if ! [ -d ./docs/tmp ]; then diff --git a/rust/docs/README.md b/rust/docs/README.md index 586cf2663..7aaa35c16 100644 --- a/rust/docs/README.md +++ b/rust/docs/README.md @@ -1,10 +1,3 @@ This is an [mdbook](https://rust-lang.github.io/mdBook/index.html) book. Minor modifications can be made without installing the mdbook tool, as the content is simple Markdown. Changes are verified on pull requests. - -To build the docs locally, you will need to build `usage-docs`: - -``` -cargo build -p taskchampion-cli --feature usage-docs --bin usage-docs -mdbook build docs/ -``` diff --git a/rust/docs/book.toml b/rust/docs/book.toml index 3ab678ad0..7e2fa9820 100644 --- a/rust/docs/book.toml +++ b/rust/docs/book.toml @@ -7,6 +7,3 @@ title = "TaskChampion" [output.html] default-theme = "ayu" - -[preprocessor.usage-docs] -command = "target/debug/usage-docs" diff --git a/rust/docs/src/SUMMARY.md b/rust/docs/src/SUMMARY.md index 942db92d2..9a3bde8c5 100644 --- a/rust/docs/src/SUMMARY.md +++ b/rust/docs/src/SUMMARY.md @@ -2,16 +2,6 @@ - [Welcome to TaskChampion](./welcome.md) * [Installation](./installation.md) - * [Using the Task Command](./using-task-command.md) - * [Reports](./reports.md) - * [Tags](./tags.md) - * [Filters](./filters.md) - * [Modifications](./modifications.md) - * [Dates and Durations](./time.md) - * [Configuration](./config-file.md) - * [Environment](./environment.md) - * [Undo](./undo.md) - * [Synchronization](./task-sync.md) * [Running the Sync Server](./running-sync-server.md) - [Internal Details](./internals.md) * [Data Model](./data-model.md) diff --git a/rust/docs/src/config-file.md b/rust/docs/src/config-file.md deleted file mode 100644 index 73dc28b60..000000000 --- a/rust/docs/src/config-file.md +++ /dev/null @@ -1,66 +0,0 @@ -# Configuration - -The `ta` command will work out-of-the-box with no configuration file, using default values. - -Configuration is read from `taskchampion.toml` 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. -This can be overridden by setting `TASKCHAMPION_CONFIG` to the configuration filename. - -The file format is [TOML](https://toml.io/). -For example: - -```toml -data_dir = "/home/myuser/.tasks" -``` - -## 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. - -## Command-Line Preferences - -* `modification_count_prompt` - when a modification will affect more than this many tasks, the `ta` command will prompt for confirmation. - A value of `0` will disable the prompts entirely. - Default: 3. - -## 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. - -## Snapshots - -* `avoid_snapshots` - If running on a CPU-, memory-, or bandwidth-constrained - device, set this to true. The effect is that this replica will wait longer - to produce a snapshot, in the hopes that other replicas will do so first. - -## Reports - -* `reports` - a mapping of each report's name to its definition. - See [Reports](./reports.md) for details. - -## Editing - -As a shortcut, the simple, top-level configuration values can be edited from the command line: - -```shell -ta config set data_dir /home/myuser/.taskchampion -``` diff --git a/rust/docs/src/environment.md b/rust/docs/src/environment.md deleted file mode 100644 index 14fea8aba..000000000 --- a/rust/docs/src/environment.md +++ /dev/null @@ -1,21 +0,0 @@ -# Environment Variables - -## Configuration - -Set `TASKCHAMPION_CONFIG` to the location of a configuration file in order to override the default location. - -## Terminal Output - -Taskchampion uses [termcolor](https://github.com/BurntSushi/termcolor) to color its output. -This library interprets [`TERM` and `NO_COLOR`](https://github.com/BurntSushi/termcolor#automatic-color-selection) to determine how it should behave, when writing to a tty. -Set `NO_COLOR` to any value to force plain-text output. - -## Debugging - -Both `ta` 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 ta add foo -``` - -The output may provide valuable clues in debugging problems. diff --git a/rust/docs/src/filters.md b/rust/docs/src/filters.md deleted file mode 100644 index e2be669d7..000000000 --- a/rust/docs/src/filters.md +++ /dev/null @@ -1,9 +0,0 @@ -# Filters - -Filters are used to select specific tasks for reports or to specify tasks to be modified. -When more than one filter is given, only tasks which match all of the filters are selected. -When no filter is given, the command implicitly selects all tasks. - -Filters can have the following forms: - - diff --git a/rust/docs/src/modifications.md b/rust/docs/src/modifications.md deleted file mode 100644 index 017969951..000000000 --- a/rust/docs/src/modifications.md +++ /dev/null @@ -1,5 +0,0 @@ -# Modifications - -Modifications can have the following forms: - - diff --git a/rust/docs/src/reports.md b/rust/docs/src/reports.md deleted file mode 100644 index 4f106e35b..000000000 --- a/rust/docs/src/reports.md +++ /dev/null @@ -1,79 +0,0 @@ -# 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 -$ ta -Id Description Active Tags -1 learn about TaskChampion +next -2 buy wedding gift * +buy -3 plant tomatoes +garden -``` - -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 (`ta 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` table. -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 (optional) -* `sort` - how to order the tasks (optional) -* `columns` - the columns of information to display for each task - -For example: - -```toml -[reports.garden] -sort = [ - { sort_by = "description" } -] -filter = [ - "status:pending", - "+garden" -] -columns = [ - { label = "ID", property = "id" }, - { label = "Description", property = "description" }, -] -``` - -The `filter` property is a list of [filters](./filters.md). -It will be merged with any filters provided on the command line when the report is invoked. - -The sort order is defined by an array of tables 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. -If `ascending` is given, it can be `true` for the default sort order, or `false` for the reverse. - -In most cases tasks are just sorted by one criterion, but a more advanced example might look like: - -```toml -[reports.garden] -sort = [ - { sort_by = "description" } - { sort_by = "uuid", ascending = false } -] -... -``` - -The available values of `sort_by` are - - - -Finally, the `columns` configuration specifies the list of columns to display. -Each element has a `label` and a `property`, as shown in the example above. - -The avaliable properties are: - - diff --git a/rust/docs/src/tags.md b/rust/docs/src/tags.md deleted file mode 100644 index cf9d80102..000000000 --- a/rust/docs/src/tags.md +++ /dev/null @@ -1,26 +0,0 @@ -# Tags - -Each task has a collection of associated tags. -Tags are short words that categorize tasks, typically written with a leading `+`, such as `+next` or `+jobsearch`. - -Tags are useful for filtering tasks in reports or on the command line. -For example, when it's time to continue the job search, `ta +jobsearch` will show pending tasks with the `jobsearch` tag. - -## Allowed Tags - -Specifically, tags must be at least one character long and cannot contain whitespace or any of the characters `+-*/(<>^! %=~`. -The first character cannot be a digit, and `:` is not allowed after the first character. -All-capital tags are reserved for synthetic tags (below) and cannot be added or removed from tasks. - -## Synthetic Tags - -Synthetic tags are present on tasks that meet specific criteria, that are commonly used for filtering. -For example, `WAITING` is set for tasks that are currently waiting. -These tags cannot be added or removed from a task, but appear and disappear as the task changes. -The following synthetic tags are defined: - -* `WAITING` - set if the task is waiting (has a `wait` property with a date in the future) -* `ACTIVE` - set if the task is active (has been started and not stopped) -* `PENDING` - set if the task is pending (not completed or deleted) -* `COMPLETED` - set if the task has been completed -* `DELETED` - set if the task has been deleted (but not yet flushed from the task list) diff --git a/rust/docs/src/task-sync.md b/rust/docs/src/task-sync.md deleted file mode 100644 index 82200ae48..000000000 --- a/rust/docs/src/task-sync.md +++ /dev/null @@ -1,49 +0,0 @@ -# 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 `ta 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. - -## Local Sync - -By default, TaskChampion syncs to a "local server", as specified by the `server_dir` configuration parameter. -This defaults to `taskchampion-sync-server` in your [data directory](https://docs.rs/dirs-next/2.0.0/dirs_next/fn.data_dir.html), but can be customized in the configuration file. - -## Remote Sync - -For remote synchronization, you will need a few pieces of information. -From the server operator, you will need an origin and a client key. -Configure these with - -```shell -ta config set server_origin "" -ta config set server_client_key "" -``` - -You will need to generate your own encryption secret. -This is used to encrypt your task history, so treat it as a password. -The following will use the `openssl` utility to generate a suitable value: - -```shell -ta config set encryption_secret $(openssl rand -hex 35) -``` - -Every replica sharing a task history should have precisely the same configuration for `server_origin`, `server_client_key`, and `encryption_secret`. - -### Adding a New Replica - -Synchronizing a new replica to an existing task history is easy: begin with an empty replica, configured for the remote server, and run `ta sync`. -The replica will download the entire task history. - -### Upgrading a Locally-Sync'd Replica - -It is possible to switch a single replica to a remote server by simply configuring for the remote server and running `ta 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/rust/docs/src/time.md b/rust/docs/src/time.md deleted file mode 100644 index 4053aea29..000000000 --- a/rust/docs/src/time.md +++ /dev/null @@ -1,48 +0,0 @@ -## Timestamps - -Times may be specified in a wide variety of convenient formats. - - * [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339) timestamps, such as `2019-10-12 07:20:50.12Z` - * A date of the format `YYYY-MM-DD` is interpreted as the _local_ midnight at the beginning of the given date. - Single-digit month and day are accepted, but the year must contain four digits. - * `now` refers to the exact current time - * `yesterday`, `today`, and `tomorrow` refer to the _local_ midnight at the beginning of the given day - * Any duration (described below) may be used as a timestamp, and is considered relative to the current time. - -Times are stored internally as UTC. - -## Durations - -Durations can be given in a dizzying array of units. -Each can be preceded by a whole number or a decimal multiplier, e.g., `3days`. -The multiplier is optional with the singular forms of the units; for example `day` is allowed. -Some of the units allow an adjectival form, such as `daily` or `annually`; this form is more readable in some cases, but otherwise has the same meaning. - - * `s`, `second`, or `seconds` - * `min`, `mins`, `minute`, or `minutes` (note that `m` not allowed, as it might also mean `month`) - * `h`, `hour`, or `hours` - * `d`, `day`, or `days` - * `w`, `week`, or `weeks` - * `mo`, or `months` (always 30 days, regardless of calendar month) - * `y`, `year`, or `years` (365 days, regardless of leap days) - -[ISO 8601 standard durations](https://en.wikipedia.org/wiki/ISO_8601#Durations) are also allowed. -While the standard does not specify the length of "P1Y" or "P1M", Taskchampion treats those as 365 and 30 days, respectively. - - -## Named Timestamps - -Some commonly used named timestamps - - * `today` Start of today - * `yesterday` Start of yesterday - * `tomorrow` Start of tomorrow - * `sod` Start of today - * `eod` End of today - * `sow` Start of the next week - * `eow` End of the week - * `eoww` End of work week - * `soww` Start of the next work week - - -![named timestamp](images/name_timestamp.png) diff --git a/rust/docs/src/undo.md b/rust/docs/src/undo.md deleted file mode 100644 index 3d6702240..000000000 --- a/rust/docs/src/undo.md +++ /dev/null @@ -1,7 +0,0 @@ -# Undo - -It's easy to make a mistake: mark the wrong task as done, or hit enter before noticing a typo in a tag name. -The `ta undo` command makes it just as easy to fix the mistake, by effectively reversing the most recent change. -Multiple invocations of `ta undo` can be used to undo multiple changes. - -The limit of this functionality is that changes which have been synchronized to the server (via `ta sync`) cannot be undone. diff --git a/rust/docs/src/using-task-command.md b/rust/docs/src/using-task-command.md deleted file mode 100644 index 355dcc898..000000000 --- a/rust/docs/src/using-task-command.md +++ /dev/null @@ -1,16 +0,0 @@ -# Using the Task Command - -The main interface to your tasks is the `ta` 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). - -> NOTE: the `task` interface does not precisely match that of TaskWarrior. - -## Subcommands - -The sections below describe each subcommand of the `ta` command. -The syntax of `[filter]` is defined in [filters](./filters.md), and that of `[modification]` in [modifications](./modifications.md). -You can also find a summary of all subcommands, as well as filters, built-in reports, and so on, with `ta help`. - -