mirror of https://gitlab.com/ceda_ei/wish
Add initial docs
This commit is contained in:
parent
c5ed5caaa6
commit
e39e955046
|
@ -0,0 +1,3 @@
|
|||
# Customization
|
||||
|
||||
TODO
|
|
@ -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)
|
|
@ -0,0 +1,3 @@
|
|||
# Themes
|
||||
|
||||
TODO
|
|
@ -0,0 +1,3 @@
|
|||
# Creating Plugins
|
||||
|
||||
TODO
|
|
@ -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).
|
|
@ -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)
|
|
@ -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. | ⏚ |
|
|
@ -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. | & |
|
|
@ -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. | - |
|
|
@ -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 |
|
|
@ -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.
|
|
@ -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 |
|
|
@ -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.
|
|
@ -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.
|
|
@ -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. | |
|
|
@ -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) |
|
|
@ -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.
|
|
@ -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.
|
|
@ -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 |
|
|
@ -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.
|
|
@ -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. | ● |
|
|
@ -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.
|
||||
|
||||
|
28
mkdocs.yml
28
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
|
||||
|
|
Loading…
Reference in New Issue