From e39e9550468abfdb5288937b7115c528dc8a4ce8 Mon Sep 17 00:00:00 2001 From: Ceda EI Date: Wed, 6 Dec 2023 18:35:53 +0530 Subject: [PATCH] Add initial docs --- docs/Customization.md | 3 ++ docs/Installation.md | 17 +++++++++++ docs/Themes.md | 3 ++ docs/development/creating_plugins.md | 3 ++ docs/development/creating_themes.md | 10 +++++++ docs/index.md | 15 ++++++++++ docs/plugins/battery.md | 18 ++++++++++++ docs/plugins/bgjobs.md | 15 ++++++++++ docs/plugins/customtext.md | 17 +++++++++++ docs/plugins/date.md | 16 +++++++++++ docs/plugins/exitcode.md | 15 ++++++++++ docs/plugins/exitcodesmiley.md | 19 +++++++++++++ docs/plugins/hostname.md | 14 ++++++++++ docs/plugins/newline.md | 14 ++++++++++ docs/plugins/path.md | 17 +++++++++++ docs/plugins/path_powerline.md | 28 +++++++++++++++++++ docs/plugins/pythonvenv.md | 14 ++++++++++ docs/plugins/space.md | 14 ++++++++++ docs/plugins/tmux.md | 14 ++++++++++ docs/plugins/username.md | 14 ++++++++++ docs/plugins/vcs.md | 24 ++++++++++++++++ docs/reference/gINIe.md | 42 ++++++++++++++++++++++++++++ mkdocs.yml | 28 +++++++++++++++++++ 23 files changed, 374 insertions(+) create mode 100644 docs/Customization.md create mode 100644 docs/Installation.md create mode 100644 docs/Themes.md create mode 100644 docs/development/creating_plugins.md create mode 100644 docs/development/creating_themes.md create mode 100644 docs/index.md create mode 100644 docs/plugins/battery.md create mode 100644 docs/plugins/bgjobs.md create mode 100644 docs/plugins/customtext.md create mode 100644 docs/plugins/date.md create mode 100644 docs/plugins/exitcode.md create mode 100644 docs/plugins/exitcodesmiley.md create mode 100644 docs/plugins/hostname.md create mode 100644 docs/plugins/newline.md create mode 100644 docs/plugins/path.md create mode 100644 docs/plugins/path_powerline.md create mode 100644 docs/plugins/pythonvenv.md create mode 100644 docs/plugins/space.md create mode 100644 docs/plugins/tmux.md create mode 100644 docs/plugins/username.md create mode 100644 docs/plugins/vcs.md create mode 100644 docs/reference/gINIe.md diff --git a/docs/Customization.md b/docs/Customization.md new file mode 100644 index 0000000..ae77531 --- /dev/null +++ b/docs/Customization.md @@ -0,0 +1,3 @@ +# Customization + +TODO diff --git a/docs/Installation.md b/docs/Installation.md new file mode 100644 index 0000000..8921c72 --- /dev/null +++ b/docs/Installation.md @@ -0,0 +1,17 @@ +# Installation + +## One step Installation + +```sh +curl https://gitlab.com/ceda_ei/wish/raw/master/install.sh | bash +``` + +## Manual Installation + ++ `cd ~/.config/` ++ `git clone https://gitlab.com/ceda_ei/wish.git` ++ `cp wish/config.default.gie wish/config.gie` + +## Customization + +Head over to [Customization](Customization.md) diff --git a/docs/Themes.md b/docs/Themes.md new file mode 100644 index 0000000..0ae2e1c --- /dev/null +++ b/docs/Themes.md @@ -0,0 +1,3 @@ +# Themes + +TODO diff --git a/docs/development/creating_plugins.md b/docs/development/creating_plugins.md new file mode 100644 index 0000000..b486a5b --- /dev/null +++ b/docs/development/creating_plugins.md @@ -0,0 +1,3 @@ +# Creating Plugins + +TODO diff --git a/docs/development/creating_themes.md b/docs/development/creating_themes.md new file mode 100644 index 0000000..c339f7b --- /dev/null +++ b/docs/development/creating_themes.md @@ -0,0 +1,10 @@ +# Creating Themes + +Themes need to define the following variables. + ++ `WISH_DEFAULT_FG` ++ `WISH_DEFAULT_BG` + +Plugins will fallback to these variables if they are not themed. + +Themes also need to define variables for plugins. For each plugin named `abc`, the theme needs to define `WISH_ABC_BG` and `WISH_ABC_FG`. Themes can optionally iterate over `WISH_PLUGINS` array to ensure to theme all elements. Check existing [themes](https://gitlab.com/ceda_ei/wish/tree/master/themes). diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..5a63fbc --- /dev/null +++ b/docs/index.md @@ -0,0 +1,15 @@ +# Wish + +A customizable bash prompt. + +## Features + +- Extremely configurable: Wish is configured by a single gINIe file +- Easy to switch themes: Switching themes is as simple as changing a single line. +- Easy custom themes: Users can override colors for plugins. +- Responsive: Adapts to terminal width. +- Easy to create plugins: Plugins are written in bash allowing great flexibility to extend. + +## Getting Started + +Head over to [Installation](Installation.md) diff --git a/docs/plugins/battery.md b/docs/plugins/battery.md new file mode 100644 index 0000000..199a73a --- /dev/null +++ b/docs/plugins/battery.md @@ -0,0 +1,18 @@ +# Battery + +Shows the amount of charge in the battery and if it is charging/discharging. + +## Add to wish + +```ini +[plugin] +name = battery +``` + +## Config options + +| Key | Meaning | Default | +|-------------|------------------------------------------|---------| +| id | ID of Battery to check. | BAT0 | +| charging | Symbol while the battery is charging. | ϟ | +| discharging | Symbol while the battery is discharging. | ⏚ | diff --git a/docs/plugins/bgjobs.md b/docs/plugins/bgjobs.md new file mode 100644 index 0000000..9378482 --- /dev/null +++ b/docs/plugins/bgjobs.md @@ -0,0 +1,15 @@ +# Background Jobs + +Shows the number of background jobs running + +## Add to wish + +```ini +[plugin] +name = bg_jobs +``` +## Config options + +| Key | Meaning | Default | +|--------|---------------------------------------------|---------| +| suffix | Suffix to add to number of background jobs. | & | diff --git a/docs/plugins/customtext.md b/docs/plugins/customtext.md new file mode 100644 index 0000000..575a487 --- /dev/null +++ b/docs/plugins/customtext.md @@ -0,0 +1,17 @@ +# Custom Text + +Display the provided custom text in the prompt. + + +## Add to wish + +```ini +[plugin] +name = custom_text +``` + +## Config options + +| Key | Meaning | Default | +|------|----------------------|:-------:| +| text | Custom text to show. | - | diff --git a/docs/plugins/date.md b/docs/plugins/date.md new file mode 100644 index 0000000..834438d --- /dev/null +++ b/docs/plugins/date.md @@ -0,0 +1,16 @@ +# Date + +Shows the current date and time. + +## Add to wish + +```ini +[plugin] +name = date +``` + +## Config options + +| Key | Meaning | Default | +|--------|---------------------------------------------------------------------------------|---------| +| format | set the date format. Refer to `FORMAT` section of `man date` for more details. | %F %T | diff --git a/docs/plugins/exitcode.md b/docs/plugins/exitcode.md new file mode 100644 index 0000000..52f0036 --- /dev/null +++ b/docs/plugins/exitcode.md @@ -0,0 +1,15 @@ +# Exit Code + +Shows the exit code of the last command if it is non-zero. + + +## Add to wish + +```ini +[plugin] +name = exit_code +``` + +## Config options + +No plugin specific config options are available. diff --git a/docs/plugins/exitcodesmiley.md b/docs/plugins/exitcodesmiley.md new file mode 100644 index 0000000..d00ddb5 --- /dev/null +++ b/docs/plugins/exitcodesmiley.md @@ -0,0 +1,19 @@ +# Exit Code Smiley + +Shows a happy/sad smiley face based on whether the last command ran successfully or not. + + +## Add to wish + +```ini +[plugin] +name = exit_code_smiley +``` + +## Config options + +| Key | Meaning | Default | +|--------------|--------------------------------------------------------------|---------| +| pass | Text to show when the last command ran successfully. | :) | +| fail | Text to show when the last command failed. | :( | +| hide_on_pass | Whether to hide the output if command executes successfully. | 0 | diff --git a/docs/plugins/hostname.md b/docs/plugins/hostname.md new file mode 100644 index 0000000..c820b40 --- /dev/null +++ b/docs/plugins/hostname.md @@ -0,0 +1,14 @@ +# Hostname + +Shows the current system's hostname. + +## Add to wish + +```ini +[plugin] +name = hostname +``` + +## Config options + +No plugin specific config options are available. diff --git a/docs/plugins/newline.md b/docs/plugins/newline.md new file mode 100644 index 0000000..79f1422 --- /dev/null +++ b/docs/plugins/newline.md @@ -0,0 +1,14 @@ +# Newline + +Adds a newline to prompt to push the next plugins into next line. + +## Add to wish + +```ini +[plugin] +name = newline +``` + +## Config options + +No plugin specific config options are available. diff --git a/docs/plugins/path.md b/docs/plugins/path.md new file mode 100644 index 0000000..61c71bf --- /dev/null +++ b/docs/plugins/path.md @@ -0,0 +1,17 @@ +# Path + +Shows the current path and whether it is writeable. + + +## Add to wish + +```ini +[plugin] +name = path +``` + +## Config options + +| Key | Meaning | Default | +|-----------------|----------------------------------------------|---------| +| no_write_suffix | Suffix if the current path is not writeable. |  | diff --git a/docs/plugins/path_powerline.md b/docs/plugins/path_powerline.md new file mode 100644 index 0000000..cd965cb --- /dev/null +++ b/docs/plugins/path_powerline.md @@ -0,0 +1,28 @@ +# Path Powerline + +Shows the current path and whether it is writeable. + +## Features + +- Powerline symbols used as path separators. +- Long paths are shrunk down to allow for more space for other plugins. + - e.g. `/usr/lib/systemd/system/` might get shortened to one of the + following based on config + screen width: `/u/l/s/system`, + `/u/l/systemd/system` or `/u/lib/systemd/system` + - This is configurable and disabled by default (check `max_perc` config) + - Recommended value for `max_perc` is `50` + + +## Add to wish + +```ini +[plugin] +name = path +``` + +## Config options + +| Key | Meaning | Default | +|-----------------|--------------------------------------------------------------|--------------| +| no_write_suffix | Suffix if the current path is not writeable. |  | +| max_perc | Maximum percentage of screen width path should take. (0-100) | 0 (disabled) | diff --git a/docs/plugins/pythonvenv.md b/docs/plugins/pythonvenv.md new file mode 100644 index 0000000..8e53e53 --- /dev/null +++ b/docs/plugins/pythonvenv.md @@ -0,0 +1,14 @@ +# Python Virtualenv + +Shows the currently active virtualenv. If the venv is `.venv`, it shows the parent directory's name. + +## Add to wish + +```ini +[plugin] +name = python_venv +``` + +## Config options + +No plugin specific config options are available. diff --git a/docs/plugins/space.md b/docs/plugins/space.md new file mode 100644 index 0000000..60195a9 --- /dev/null +++ b/docs/plugins/space.md @@ -0,0 +1,14 @@ +# Space + +Simple plugin that adds an empty space. + +## Add to wish + +```ini +[plugin] +name = space +``` + +## Config options + +No plugin specific config options are available. diff --git a/docs/plugins/tmux.md b/docs/plugins/tmux.md new file mode 100644 index 0000000..8507273 --- /dev/null +++ b/docs/plugins/tmux.md @@ -0,0 +1,14 @@ +# Tmux Detached Sessions + +Lists the number of tmux sessions that are detached. + +### Add to wish +```ini +[plugin] +name = vcs +``` +## Config options + +| Key | Meaning | Default | +|--------|--------------------------------------------------|---------| +| suffix | suffix to add after number of detached sessions. | d | diff --git a/docs/plugins/username.md b/docs/plugins/username.md new file mode 100644 index 0000000..a2bd458 --- /dev/null +++ b/docs/plugins/username.md @@ -0,0 +1,14 @@ +# Username + +Shows the current unix username + +## Add to wish + +```ini +[plugin] +name = username +``` + +## Config options + +No plugin specific config options are available. diff --git a/docs/plugins/vcs.md b/docs/plugins/vcs.md new file mode 100644 index 0000000..9181f72 --- /dev/null +++ b/docs/plugins/vcs.md @@ -0,0 +1,24 @@ +# Version Control System (Git) + +Provides the state of the git repository in the current directory. + +## Features + +- Notifies if there are any untracked symbols +- Name of the current branch +- Amount of changes (additions/subtractions) + +## Add to wish + +```ini +[plugin] +name = vcs +``` + +## Config options + +| Key | Meaning | Default | +|----------------------|-----------------------------------------------------------------|---------| +| git_symbol | Symbol to indicate that the current directory is a git repo. |  | +| default | Symbol to display when the current directory is not a git repo. | $ | +| git_untracked_symbol | Symbol to show if the current git repo has untracked files. | ● | diff --git a/docs/reference/gINIe.md b/docs/reference/gINIe.md new file mode 100644 index 0000000..336b9d8 --- /dev/null +++ b/docs/reference/gINIe.md @@ -0,0 +1,42 @@ +# gINIe file format + + +Customization of wish is done using a gINIe file (format specific to wish) +which is an extended INI config file. The default location for config file is +`~/.config/wish/config.gie`. The default config file is automatically copied +over. The location can be customized using `WISH_CONFIG_FILE` variable. +Multiple config files can be supplied as an array to `WISH_CONFIG_FILE`. + +Comments start with a `#` or `;` and always exist on a line of their own. + +Key value pairs are in the form of `key = value`. Keys cannot have whitespaces +or `=` in them. Values can have any character as part of them. Surrounding +spaces in values are stripped away. To keep surrounding spaces as a part of +the value. Although, keys are case-sensitive in gINIe, wish treats them case- +insensitively. + +Block names are enclosed in `[]` (e.g. `[core]`). Block names are case +sensitive. All key value pairs after a block starts and before the next block +begins are considered a part of that block. All key value pairs must be in a +block. + +Available Blocks: + ++ `core`: Core block configures Wish itself. Available keys are: + - `auto_newline`: Automatically add a newline if last line of output + doesn't end in newline. (0 to disable, 1 to enable) + - `theme`: Wish theme. + - `powerline`: Enable / Disable powerline. (0 to disable, 1 to enable) ++ `plugin`: Adds a plugin to the section the block is added to. All config for + that plugin goes there. Check wiki for details on available keys for + plugins. The key "name" defines the plugin to use. Plugin blocks + outside a section are ignored. + +Section names are enclosed in `||` (e.g. `|left|`). All blocks after a section +starts and before the next section begins are considered a part of that +section. Blocks don't necessarily need to be in a section. + +Available sections are `left`, `right` for left prompt and right prompt +respectively. + + diff --git a/mkdocs.yml b/mkdocs.yml index 8065bb8..646df8c 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -6,3 +6,31 @@ theme: readthedocs markdown_extensions: - toc: permalink: true + + +nav: + - index.md + - Installation.md + - Customization.md + - Themes.md + - plugins: + - plugins/battery.md + - plugins/bgjobs.md + - plugins/customtext.md + - plugins/date.md + - plugins/exitcode.md + - plugins/exitcodesmiley.md + - plugins/hostname.md + - plugins/newline.md + - plugins/path.md + - plugins/path_powerline.md + - plugins/pythonvenv.md + - plugins/space.md + - plugins/tmux.md + - plugins/username.md + - plugins/vcs.md + - development: + - development/creating_plugins.md + - development/creating_themes.md + - reference: + - reference/gINIe.md