Add initial docs

This commit is contained in:
Ceda EI 2023-12-06 18:35:53 +05:30
parent c5ed5caaa6
commit e39e955046
23 changed files with 374 additions and 0 deletions

3
docs/Customization.md Normal file
View File

@ -0,0 +1,3 @@
# Customization
TODO

17
docs/Installation.md Normal file
View File

@ -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)

3
docs/Themes.md Normal file
View File

@ -0,0 +1,3 @@
# Themes
TODO

View File

@ -0,0 +1,3 @@
# Creating Plugins
TODO

View File

@ -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).

15
docs/index.md Normal file
View File

@ -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)

18
docs/plugins/battery.md Normal file
View File

@ -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. | ⏚ |

15
docs/plugins/bgjobs.md Normal file
View File

@ -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. | & |

View File

@ -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. | - |

16
docs/plugins/date.md Normal file
View File

@ -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 |

15
docs/plugins/exitcode.md Normal file
View File

@ -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.

View File

@ -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 |

14
docs/plugins/hostname.md Normal file
View File

@ -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.

14
docs/plugins/newline.md Normal file
View File

@ -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.

17
docs/plugins/path.md Normal file
View File

@ -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. |  |

View File

@ -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) |

View File

@ -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.

14
docs/plugins/space.md Normal file
View File

@ -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.

14
docs/plugins/tmux.md Normal file
View File

@ -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 |

14
docs/plugins/username.md Normal file
View File

@ -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.

24
docs/plugins/vcs.md Normal file
View File

@ -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. | ● |

42
docs/reference/gINIe.md Normal file
View File

@ -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.

View File

@ -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