diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 0000000..e60fdf1 --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,33 @@ +name: Deploy docs +on: + push: + branches: + - master +jobs: + deploy: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v2 + with: + submodules: "recursive" + fetch-depth: 0 + - name: Setup Python + uses: actions/setup-python@v1 + with: + python-version: '3.8' + architecture: 'x64' + - name: Install dependencies + run: | + python3 -m pip install --upgrade pip # install pip + python3 -m pip install mkdocs # install mkdocs + python3 -m pip install mkdocs-material # install material theme + python3 -m pip install pygments pymdown-extensions mkdocs-material-extensions termcolor mkdocs-material mkdocs-macros-plugin + - name: Build site + run: mkdocs build + - name: Github Pages Deploy + uses: peaceiris/actions-gh-pages@v3 + with: + personal_token: ${{ secrets.GITHUB_TOKEN }} + publish_branch: gh-pages + publish_dir: ./site + force_orphan: true diff --git a/README.md b/README.md index 60859c6..91dd326 100644 --- a/README.md +++ b/README.md @@ -11,268 +11,4 @@ A Terminal User Interface for [Taskwarrior](https://taskwarrior.org/). ![](https://user-images.githubusercontent.com/1813121/97066323-acd41500-1571-11eb-90c2-d74faa21e1ad.png) -## Installation - -Unless otherwise specified, you will need to install `taskwarrior` first. See for more information. - -**Manual** ( _Recommended_ ) [![](https://img.shields.io/github/v/tag/kdheepak/taskwarrior-tui)](https://github.com/kdheepak/taskwarrior-tui/releases/latest) [![](https://img.shields.io/github/downloads/kdheepak/taskwarrior-tui/total)](https://github.com/kdheepak/taskwarrior-tui/releases/latest) - -1. Download the tar.gz file for your OS from [the latest release](https://github.com/kdheepak/taskwarrior-tui/releases/latest). -2. Unzip the tar.gz file -3. Run with `./taskwarrior-tui`. - -**Install from source** [![](https://img.shields.io/badge/branch-master-red)](https://github.com/kdheepak/taskwarrior-tui) - -```bash -git clone https://github.com/kdheepak/taskwarrior-tui.git -cd taskwarrior-tui -cargo build --release -``` - -**Using [`brew`](https://brew.sh/)** [![](https://img.shields.io/homebrew/v/taskwarrior-tui)](https://formulae.brew.sh/formula/taskwarrior-tui) [![](https://img.shields.io/homebrew/installs/dy/taskwarrior-tui)](https://formulae.brew.sh/formula/taskwarrior-tui) - - -This installs `task` from `homebrew` as well. - -```bash -brew install taskwarrior-tui -``` - -**Installation for Arch Linux** [![](https://img.shields.io/archlinux/v/community/x86_64/taskwarrior-tui)](https://archlinux.org/packages/community/x86_64/taskwarrior-tui/) [![](https://img.shields.io/aur/version/taskwarrior-tui-git)](https://aur.archlinux.org/packages/taskwarrior-tui-git/) - -Use [pacman](https://wiki.archlinux.org/index.php/Pacman) to install it from the [community repository](https://archlinux.org/packages/community/x86_64/taskwarrior-tui/): - -```bash -pacman -S taskwarrior-tui -``` - -Or use your favorite [AUR helper](https://wiki.archlinux.org/index.php/AUR_helpers) to download the [git](https://aur.archlinux.org/packages/taskwarrior-tui-git/) package maintained by [**@loki7990**](https://github.com/loki7990). For example: - -```bash -yay -S taskwarrior-tui-git # build from source master -``` - -**Using [`snap`](https://snapcraft.io/)** [![](https://snapcraft.io/taskwarrior-tui/badge.svg)](https://snapcraft.io/taskwarrior-tui) - -```bash -snap install taskwarrior-tui -``` - - - -**Using [`zdharma/zinit`](https://github.com/zdharma/zinit)** [![](https://img.shields.io/github/v/tag/kdheepak/taskwarrior-tui)](https://github.com/kdheepak/taskwarrior-tui/releases/latest) - -Add the following to your `~/.zshrc`: - -```zsh -zinit ice wait:2 lucid extract"" from"gh-r" as"command" mv"taskwarrior-tui* -> tt" -zinit load kdheepak/taskwarrior-tui -``` - -## Usage - -_Tip_: Alias `tt` to `taskwarrior-tui`. - -Add the following to your dotfiles (e.g. `~/.bashrc`, `~/.zshrc`): - -``` -alias tt="taskwarrior-tui" -``` - -### See it in action: - -
- - Click to expand! - -![](https://user-images.githubusercontent.com/1813121/89620056-4ed64200-d84c-11ea-9153-9e08bc26d3b4.gif) - -
- -### Easy to use interface: - -
- - Click to expand! - -See [KEYBINDINGS.md](./KEYBINDINGS.md) for full list. - -![](https://user-images.githubusercontent.com/1813121/88654924-40896880-d08b-11ea-8709-b29cc970da4c.gif) - -
- -### Context switcher: - -
- - Click to expand! - -![](https://user-images.githubusercontent.com/1813121/97959948-a746ae00-1d6d-11eb-9ffe-8f76f2a2b32d.gif) - -
- -### `readline`-like functionality: - -
- - Click to expand! - -- `` : Go to beginning of the line -- `` : Go to end of the line -- `` : Delete from beginning of the line -- `` : Delete to end of the line -- `` : Delete previous word - -![](https://user-images.githubusercontent.com/1813121/95651612-ce7cc900-0aa8-11eb-8686-42442ed9ee43.gif) - -
- -### Calendar view - -
- - Click to expand! - -`taskwarrior-tui` supports a Calendar view, which you can get to by hitting the `]` key: - -![](https://user-images.githubusercontent.com/1813121/96957124-0c211f00-14b7-11eb-9d29-b3b68420af44.gif) - -This highlights the days for your due tasks in a calendar view. -You can configure the number of months in a row by changing the `uda.taskwarrior-tui.calendar.months-per-row` attribute in your `taskrc` file. -See the next section for more information. - -You can switch back to the task view by hitting the `[` key. - -
- -### Configure `taskwarrior-tui` using `~/.taskrc`: - -
- - Click to expand! - -`taskwarrior-tui` reads values from your `taskwarrior`'s `taskrc` file (default: `~/.taskrc`). - -![](https://user-images.githubusercontent.com/1813121/96684390-bf173e80-1338-11eb-971c-ae64233d142e.png) - -For example, `color.active` is used to style the active task. -If you would like to try it, open your `taskrc` file and change `color.active=white on blue`. - -So `color.active` will take precedence over `color.overdue`. You can see what `color.active` is by running `task show color.active` in your favorite shell prompt. - -The following color attributes are supported: - -```plaintext -color.deleted -color.completed -color.active -color.overdue -color.scheduled -color.due.today -color.due -color.blocked -color.blocking -color.recurring -color.tagged -``` - -Other `taskwarrior-tui` configuration options are possible using the user defined attribute feature of `taskwarrior`. -All `taskwarrior-tui` specific configuration options will begin with `uda.taskwarrior-tui.`. -The following is a full list of all the options available and their default values implemented by `taskwarrior-tui` if not defined in your `taskrc` file. - -```plaintext -uda.taskwarrior-tui.selection.indicator=• -uda.taskwarrior-tui.selection.bold=yes -uda.taskwarrior-tui.selection.italic=no -uda.taskwarrior-tui.selection.dim=no -uda.taskwarrior-tui.selection.blink=no -uda.taskwarrior-tui.calendar.months-per-row=4 -uda.taskwarrior-tui.task-report.show-info=true -uda.taskwarrior-tui.task-report.looping=true -uda.taskwarrior-tui.style.context.active=black on rgb444 -uda.taskwarrior-tui.style.calendar.title=black on rgb444 -``` - -And here are the default key bindings: - -```plaintext -uda.taskwarrior-tui.keyconfig.quit=q -uda.taskwarrior-tui.keyconfig.refresh=r -uda.taskwarrior-tui.keyconfig.go-to-bottom=G -uda.taskwarrior-tui.keyconfig.go-to-top=g -uda.taskwarrior-tui.keyconfig.down=j -uda.taskwarrior-tui.keyconfig.up=k -uda.taskwarrior-tui.keyconfig.page-down=J -uda.taskwarrior-tui.keyconfig.page-up=K -uda.taskwarrior-tui.keyconfig.delete=x -uda.taskwarrior-tui.keyconfig.done=d -uda.taskwarrior-tui.keyconfig.start-stop=s -uda.taskwarrior-tui.keyconfig.undo=u -uda.taskwarrior-tui.keyconfig.edit=e -uda.taskwarrior-tui.keyconfig.modify=m -uda.taskwarrior-tui.keyconfig.shell=! -uda.taskwarrior-tui.keyconfig.log=l -uda.taskwarrior-tui.keyconfig.add=a -uda.taskwarrior-tui.keyconfig.annotate=A -uda.taskwarrior-tui.keyconfig.filter=/ -uda.taskwarrior-tui.keyconfig.zoom=z -uda.taskwarrior-tui.keyconfig.context-menu=c -uda.taskwarrior-tui.keyconfig.next-tab=] -uda.taskwarrior-tui.keyconfig.previous-tab=[ -``` - -
- -#### Configure user defined shortcuts: - -
- - Click to expand! - -You can configure shortcuts to execute custom commands from your `taskwarrior`'s `taskrc` file (default: `~/.taskrc`). -You can do this by mapping a shortcut to an executable file: - -```plaintext -uda.taskwarrior-tui.shortcuts.1=~/.config/taskwarrior-tui/shortcut-scripts/add-personal-tag.sh -uda.taskwarrior-tui.shortcuts.2=~/.config/taskwarrior-tui/shortcut-scripts/sync.sh -... -``` - -The file can have any name in any location, but must be executable. -By default, keys `1`-`9` are available to run shortcuts. - -When you hit the shortcut, the script will be executed with the `selected_task_uuid` as an argument: - -```bash -~/.config/taskwarrior-tui/shortcut-scripts/add-personal-tag.sh $selected_tasks_uuid -``` - -For example, you can add the `personal` tag to the currently selected task with the following script in `~/.config/taskwarrior-tui/shortcut-scripts/add-personal-tag.sh` : - -```plaintext -task rc.bulk=0 rc.confirmation=off rc.dependency.confirmation=off rc.recurrence.confirmation=off "$@" modify +personal -``` - -By default, shortcuts are linked to the `1-9` number row keys. -They can be customized as any other keys through `uda.taskwarrior-tui.keyconfig.shortcut1=`. -For example: - -```plaintext -uda.taskwarrior-tui.keyconfig.shortcut1=n -``` - -You can set up shortcuts to run `task sync` or any custom bash script that you'd like. - -
- -# Related - -For a similar effort, check out `vit`: - -- `vit`: +See for documentation. diff --git a/docs/configuration/advanced.md b/docs/configuration/advanced.md new file mode 100644 index 0000000..bd2db27 --- /dev/null +++ b/docs/configuration/advanced.md @@ -0,0 +1,54 @@ +# Advanced configuration + +Other `taskwarrior-tui` configuration options are possible using the user defined attribute feature of `taskwarrior`. +All `taskwarrior-tui` specific configuration options will begin with `uda.taskwarrior-tui.`. +The following is a full list of all the options available and their default values implemented by `taskwarrior-tui` if not defined in your `taskrc` file. + +```plaintext +uda.taskwarrior-tui.selection.indicator=• +uda.taskwarrior-tui.selection.bold=yes +uda.taskwarrior-tui.selection.italic=no +uda.taskwarrior-tui.selection.dim=no +uda.taskwarrior-tui.selection.blink=no +uda.taskwarrior-tui.calendar.months-per-row=4 +uda.taskwarrior-tui.task-report.show-info=true +uda.taskwarrior-tui.task-report.looping=true +uda.taskwarrior-tui.style.context.active=black on rgb444 +uda.taskwarrior-tui.style.calendar.title=black on rgb444 +``` + +## Configure user defined shortcuts: + +You can configure shortcuts to execute custom commands from your `taskwarrior`'s `taskrc` file (default: `~/.taskrc`). +You can do this by mapping a shortcut to an executable file: + +```plaintext +uda.taskwarrior-tui.shortcuts.1=~/.config/taskwarrior-tui/shortcut-scripts/add-personal-tag.sh +uda.taskwarrior-tui.shortcuts.2=~/.config/taskwarrior-tui/shortcut-scripts/sync.sh +... +``` + +The file can have any name in any location, but must be executable. +By default, keys `1`-`9` are available to run shortcuts. + +When you hit the shortcut, the script will be executed with the `selected_task_uuid` as an argument: + +```bash +~/.config/taskwarrior-tui/shortcut-scripts/add-personal-tag.sh $selected_tasks_uuid +``` + +For example, you can add the `personal` tag to the currently selected task with the following script in `~/.config/taskwarrior-tui/shortcut-scripts/add-personal-tag.sh` : + +```plaintext +task rc.bulk=0 rc.confirmation=off rc.dependency.confirmation=off rc.recurrence.confirmation=off "$@" modify +personal +``` + +By default, shortcuts are linked to the `1-9` number row keys. +They can be customized as any other keys through `uda.taskwarrior-tui.keyconfig.shortcut1=`. +For example: + +```plaintext +uda.taskwarrior-tui.keyconfig.shortcut1=n +``` + +You can set up shortcuts to run `task sync` or any custom bash script that you'd like. diff --git a/docs/configuration/colors.md b/docs/configuration/colors.md new file mode 100644 index 0000000..4da45ac --- /dev/null +++ b/docs/configuration/colors.md @@ -0,0 +1,26 @@ +# Color configuration + +`taskwarrior-tui` reads values from your `taskwarrior`'s `taskrc` file (default: `~/.taskrc`). + +![](https://user-images.githubusercontent.com/1813121/96684390-bf173e80-1338-11eb-971c-ae64233d142e.png) + +For example, `color.active` is used to style the active task. +If you would like to try it, open your `taskrc` file and change `color.active=white on blue`. + +So `color.active` will take precedence over `color.overdue`. You can see what `color.active` is by running `task show color.active` in your favorite shell prompt. + +The following color attributes are supported: + +```plaintext +color.deleted +color.completed +color.active +color.overdue +color.scheduled +color.due.today +color.due +color.blocked +color.blocking +color.recurring +color.tagged +``` diff --git a/docs/configuration/keys.md b/docs/configuration/keys.md new file mode 100644 index 0000000..9f76ac0 --- /dev/null +++ b/docs/configuration/keys.md @@ -0,0 +1,32 @@ +# Key configuration + +Configure `taskwarrior-tui` using `~/.taskrc`: + +`taskwarrior-tui` reads values from your `taskwarrior`'s `taskrc` file (default: `~/.taskrc`). + + +```plaintext +uda.taskwarrior-tui.keyconfig.quit=q +uda.taskwarrior-tui.keyconfig.refresh=r +uda.taskwarrior-tui.keyconfig.go-to-bottom=G +uda.taskwarrior-tui.keyconfig.go-to-top=g +uda.taskwarrior-tui.keyconfig.down=j +uda.taskwarrior-tui.keyconfig.up=k +uda.taskwarrior-tui.keyconfig.page-down=J +uda.taskwarrior-tui.keyconfig.page-up=K +uda.taskwarrior-tui.keyconfig.delete=x +uda.taskwarrior-tui.keyconfig.done=d +uda.taskwarrior-tui.keyconfig.start-stop=s +uda.taskwarrior-tui.keyconfig.undo=u +uda.taskwarrior-tui.keyconfig.edit=e +uda.taskwarrior-tui.keyconfig.modify=m +uda.taskwarrior-tui.keyconfig.shell=! +uda.taskwarrior-tui.keyconfig.log=l +uda.taskwarrior-tui.keyconfig.add=a +uda.taskwarrior-tui.keyconfig.annotate=A +uda.taskwarrior-tui.keyconfig.filter=/ +uda.taskwarrior-tui.keyconfig.zoom=z +uda.taskwarrior-tui.keyconfig.context-menu=c +uda.taskwarrior-tui.keyconfig.next-tab=] +uda.taskwarrior-tui.keyconfig.previous-tab=[ +``` diff --git a/docs/developer/guide.md b/docs/developer/guide.md new file mode 100644 index 0000000..67ad349 --- /dev/null +++ b/docs/developer/guide.md @@ -0,0 +1,11 @@ +# Developer guide + +## Docs + +See `docs/` folder in the repository. + +## Internals of `taskwarrior-tui` + + + +`taskwarrior-tui` is a state driven terminal user interface. diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..db524ea --- /dev/null +++ b/docs/index.md @@ -0,0 +1,12 @@ +# `taskwarrior-tui` + +[![CI](https://github.com/kdheepak/taskwarrior-tui/workflows/CI/badge.svg)](https://github.com/kdheepak/taskwarrior-tui/actions?query=workflow%3ACI) +[![](https://img.shields.io/github/license/kdheepak/taskwarrior-tui)](./LICENSE) +[![](https://img.shields.io/github/v/release/kdheepak/taskwarrior-tui)](https://github.com/kdheepak/taskwarrior-tui/releases/latest) +[![](https://img.shields.io/static/v1?label=platform&message=linux-64%20|%20osx-64%20|%20win-32%20|%20win-64&color=lightgrey)](https://github.com/kdheepak/taskwarrior-tui/releases/latest) +[![](https://img.shields.io/github/languages/top/kdheepak/taskwarrior-tui)](https://github.com/kdheepak/taskwarrior-tui) +[![](https://img.shields.io/coveralls/github/kdheepak/taskwarrior-tui)](https://coveralls.io/github/kdheepak/taskwarrior-tui) + +A Terminal User Interface for [Taskwarrior](https://taskwarrior.org/). + +![](https://user-images.githubusercontent.com/1813121/97066323-acd41500-1571-11eb-90c2-d74faa21e1ad.png) diff --git a/docs/installation.md b/docs/installation.md new file mode 100644 index 0000000..270b26c --- /dev/null +++ b/docs/installation.md @@ -0,0 +1,56 @@ + +# Installation + +Unless otherwise specified, you will need to install `taskwarrior` first. See for more information. + +**Manual** ( _Recommended_ ) [![](https://img.shields.io/github/v/tag/kdheepak/taskwarrior-tui)](https://github.com/kdheepak/taskwarrior-tui/releases/latest) [![](https://img.shields.io/github/downloads/kdheepak/taskwarrior-tui/total)](https://github.com/kdheepak/taskwarrior-tui/releases/latest) + +1. Download the tar.gz file for your OS from [the latest release](https://github.com/kdheepak/taskwarrior-tui/releases/latest). +2. Unzip the tar.gz file +3. Run with `./taskwarrior-tui`. + +**Install from source** [![](https://img.shields.io/badge/branch-master-red)](https://github.com/kdheepak/taskwarrior-tui) + +```bash +git clone https://github.com/kdheepak/taskwarrior-tui.git +cd taskwarrior-tui +cargo build --release +``` + +**Using [`brew`](https://brew.sh/)** [![](https://img.shields.io/homebrew/v/taskwarrior-tui)](https://formulae.brew.sh/formula/taskwarrior-tui) [![](https://img.shields.io/homebrew/installs/dy/taskwarrior-tui)](https://formulae.brew.sh/formula/taskwarrior-tui) + + +This installs `task` from `homebrew` as well. + +```bash +brew install taskwarrior-tui +``` + +**Installation for Arch Linux** [![](https://img.shields.io/archlinux/v/community/x86_64/taskwarrior-tui)](https://archlinux.org/packages/community/x86_64/taskwarrior-tui/) [![](https://img.shields.io/aur/version/taskwarrior-tui-git)](https://aur.archlinux.org/packages/taskwarrior-tui-git/) + +Use [pacman](https://wiki.archlinux.org/index.php/Pacman) to install it from the [community repository](https://archlinux.org/packages/community/x86_64/taskwarrior-tui/): + +```bash +pacman -S taskwarrior-tui +``` + +Or use your favorite [AUR helper](https://wiki.archlinux.org/index.php/AUR_helpers) to download the [git](https://aur.archlinux.org/packages/taskwarrior-tui-git/) package maintained by [**@loki7990**](https://github.com/loki7990). For example: + +```bash +yay -S taskwarrior-tui-git # build from source master +``` + +**Using [`snap`](https://snapcraft.io/)** [![](https://snapcraft.io/taskwarrior-tui/badge.svg)](https://snapcraft.io/taskwarrior-tui) + +```bash +snap install taskwarrior-tui +``` + +**Using [`zdharma/zinit`](https://github.com/zdharma/zinit)** [![](https://img.shields.io/github/v/tag/kdheepak/taskwarrior-tui)](https://github.com/kdheepak/taskwarrior-tui/releases/latest) + +Add the following to your `~/.zshrc`: + +```zsh +zinit ice wait:2 lucid extract"" from"gh-r" as"command" mv"taskwarrior-tui* -> tt" +zinit load kdheepak/taskwarrior-tui +``` diff --git a/docs/quick_start.md b/docs/quick_start.md new file mode 100644 index 0000000..75050af --- /dev/null +++ b/docs/quick_start.md @@ -0,0 +1,16 @@ +# Quick Start + +1. Install `taskwarrior` and `taskwarrior-tui`. +2. Run the following in a shell. + `$ taskwarrior-tui` +3. Use `vim` like keys to navigate your task list. Press `?` for more information. + +_Tip_: Alias `tt` to `taskwarrior-tui`. + +Add the following to your dotfiles (e.g. `~/.bashrc`, `~/.zshrc`): + +``` +alias tt="taskwarrior-tui" +``` + +![](https://user-images.githubusercontent.com/1813121/89620056-4ed64200-d84c-11ea-9153-9e08bc26d3b4.gif) diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..eceeb14 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,52 @@ +site_name: taskwarrior-tui - A terminal user interface for taskwarrior +site_url: https://kdheepak.com/taskwarrior-tui +site_author: Dheepak Krishnamurthy + +# Source code repository +repo_name: kdheepak/taskwarrior-tui +repo_url: https://github.com/kdheepak/taskwarrior-tui + +# Copyright +copyright: Copyright © 2021 Dheepak Krishnamurthy + +markdown_extensions: + - admonition + - attr_list + - footnotes + - pymdownx.highlight + - pymdownx.superfences + +# Plugins +plugins: + - search + +# Theme +theme: + name: material + favicon: assets/favicon.png + features: + - navigation.tabs + include_search_page: false + language: en + palette: + primary: deep blue + search_index_only: true + +# Customization +extra: + social: + - icon: fontawesome/brands/github + link: https://github.com/kdheepak + +# Page tree +nav: + - Home: index.md + - Getting Started: + - Installation: installation.md + - Quick Start: quick_start.md + - Configuration: + - Key configuration: configuration/keys.md + - Color configuration: configuration/colors.md + - Advanced: configuration/advanced.md + # - Developer Guide: + # - Guide: developer/guide.md