Marty/topen
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

doc: Add configuration description

Browse source
This commit is contained in:
Marty Oehme 2025-04-07 11:31:40 +02:00
parent 4227465bfb
commit f3930ae4c7
Signed by: Marty
GPG key ID: 4E535BC19C61886E
1 changed files with 49 additions and 19 deletions
Download patch file Download diff file Expand all files Collapse all files

68
README.md
View file

@ -14,13 +14,6 @@ to let you see that there exists a note file next time you view the task.
Should just work as-is without additional configuration in most modern taskwarrior setups.[^moderntw]
[^moderntw]: The script assumes your taskwarrior setup follows the XDG base directory suggestions. That means,
taskrc in `$XDG_CONFIG_HOME/task/taskrc`, usually `~/.config/task/taskrc`. Furthermore, at the moment it
assumes the taskwarrior _data_ residing in the `$XDG_DATA_HOME/task` directory. This will diverge from
many taskwarrior setups still and can be set through the cli option `--task-data`. The idea is for future
`topen` versions to recognize the task data directory from the taskrc file itself but this has not been
implemented.
Can be configured through environment variables or cli options, see below.
Can be used as-is with the `topen` command or directly from taskwarrior by being aliased in your `taskrc`:
@ -59,22 +52,59 @@ Only has [tasklib](https://github.com/GothenburgBitFactory/tasklib) as a depende
## Configuration
```python
TASK_RC = os.getenv("TASKRC", "~/.config/task/taskrc") # not implemented yet
TASK_DATA_DIR = os.getenv("TASKDATA", "~/.local/share/task")
TOPEN_DIR = os.getenv("TOPEN_DIR", "~/.local/share/task/notes")
TOPEN_EXT = os.getenv("TOPEN_EXT", "md")
TOPEN_ANNOT = os.getenv("TOPEN_ANNOT", "Note")
TOPEN_EDITOR = os.getenv("EDITOR") or os.getenv("VISUAL", "nano")
TOPEN_QUIET = os.getenv("TOPEN_QUIET", False)
By default the script generally assumes your taskwarrior setup follows the XDG
base directory suggestions.
That means, taskrc in `$XDG_CONFIG_HOME/task/taskrc`, usually
`~/.config/task/taskrc`. Furthermore, at the moment it assumes the taskwarrior
_data_ residing in the `$XDG_DATA_HOME/task` directory. This may diverge from
taskwarrior setups still.
This program can be configured in 3 different ways: options set in your regular taskwarrior `taskrc` file,
environment variables or options given on the command line.
### Taskrc configuration
All options can be changed directly in your taskrc file.
This may be most useful for settings which do not change often for you,
such as the note extension or notes directory.
The following settings are supported:
```ini
data.location # used for the taskwarrior data directory
notes.dir # set the notes directory itself
notes.ext # set the note file extension
notes.annot # set the annotation added to tasks with notes
notes.editor # set the editor used to open notes
notes.quiet # set topen to hide all verbose information during use
```
These are all environment variables offered, needs improved documentation.
<!-- TODO: IMPROVE DOC -->
Ultimately the goal would probably be to support reading from a taskwarrior 'taskrc' file,
which can then be optionally overwritten with env variables,
which can then be optionally overwritten with cli options.
This is not fully implemented -- we support the above environment variables
and cli options, that's it.
### Environment variables
Each option can be changed through setting the corresponding environment variable.
These are the same as the `taskrc` file options with a prepended `TOPEN_` and dots turned to underscores.
The following settings are supported:
```bash
TASKRC= # taskwarrior config file location
TASKDATA= # taskwarrior data directory location
TOPEN_NOTES_DIR= # set the notes directory itself
TOPEN_NOTES_EXT= # set the note file extension
TOPEN_NOTES_ANNOT= # set the annotation added to tasks with notes
TOPEN_NOTES_EDITOR= notes.editor # set the editor used to open notes
TOPEN_NOTES_QUIET= # set topen to hide all verbose information during use
```
### CLI options
Finally, each option can be set through the cli itself.
To find out all the available options use `topen --help`.