diff options
Diffstat (limited to 'docs/content/configuration')
| -rw-r--r-- | docs/content/configuration/command-line-flags.md | 45 | ||||
| -rw-r--r-- | docs/content/configuration/config-file/data-filtering.md | 46 | ||||
| -rw-r--r-- | docs/content/configuration/config-file/default-config.md | 11 | ||||
| -rw-r--r-- | docs/content/configuration/config-file/flags.md | 37 | ||||
| -rw-r--r-- | docs/content/configuration/config-file/layout.md | 57 | ||||
| -rw-r--r-- | docs/content/configuration/config-file/theming.md | 31 |
6 files changed, 227 insertions, 0 deletions
diff --git a/docs/content/configuration/command-line-flags.md b/docs/content/configuration/command-line-flags.md new file mode 100644 index 00000000..ae99ad7c --- /dev/null +++ b/docs/content/configuration/command-line-flags.md @@ -0,0 +1,45 @@ +# Flags + +!!! Warning + + This section is in progress, and is just copied from the old documentation. + +The following flags can be provided to bottom in the command line to change the behaviour of the program (run `btm --help` for more information on each flag): + +| Flag | Behaviour | +| ------------------------------------- | -------------------------------------------------------------- | +| `--autohide_time` | Temporarily shows the time scale in graphs. | +| `-b, --basic` | Hides graphs and uses a more basic look. | +| `--battery` | Shows the battery widget. | +| `-S, --case_sensitive` | Enables case sensitivity by default. | +| `-c, --celsius` | Sets the temperature type to Celsius. | +| `--color <COLOR SCHEME>` | Use a color scheme, use --help for supported values. | +| `-C, --config <CONFIG PATH>` | Sets the location of the config file. | +| `-u, --current_usage` | Sets process CPU% to be based on current CPU%. | +| `-t, --default_time_value <MS>` | Default time value for graphs in ms. | +| `--default_widget_count <INT>` | Sets the n'th selected widget type as the default. | +| `--default_widget_type <WIDGET TYPE>` | Sets the default widget type, use --help for more info. | +| `--disable_advanced_kill` | Hides advanced options to stop a process on Unix-like systems. | +| `--disable_click` | Disables mouse clicks. | +| `-m, --dot_marker` | Uses a dot marker for graphs. | +| `-f, --fahrenheit` | Sets the temperature type to Fahrenheit. | +| `-g, --group` | Groups processes with the same name by default. | +| `-h, --help` | Prints help information. Use --help for more info. | +| `-a, --hide_avg_cpu` | Hides the average CPU usage. | +| `--hide_table_gap` | Hides the spacing between table headers and entries. | +| `--hide_time` | Completely hides the time scaling. | +| `-k, --kelvin` | Sets the temperature type to Kelvin. | +| `-l, --left_legend` | Puts the CPU chart legend to the left side. | +| `--mem_as_value` | Defaults to showing process memory usage by value. | +| `--network_use_binary_prefix` | Displays the network widget with binary prefixes. | +| `--network_use_bytes` | Displays the network widget using bytes. | +| `--network_use_log` | Displays the network widget with a log scale. | +| `--process_command` | Show processes as their commands by default. | +| `-r, --rate <MS>` | Sets a refresh rate in ms. | +| `-R, --regex` | Enables regex by default. | +| `--show_table_scroll_position` | Shows the scroll position tracker in table widgets. | +| `-d, --time_delta <MS>` | The amount in ms changed upon zooming. | +| `-T, --tree` | Defaults to showing the process widget in tree mode. | +| `--use_old_network_legend` | DEPRECATED - uses the older network legend. | +| `-V, --version` | Prints version information. | +| `-W, --whole_word` | Enables whole-word matching by default. | diff --git a/docs/content/configuration/config-file/data-filtering.md b/docs/content/configuration/config-file/data-filtering.md new file mode 100644 index 00000000..0bbc7b45 --- /dev/null +++ b/docs/content/configuration/config-file/data-filtering.md @@ -0,0 +1,46 @@ +# Data Filtering + +!!! Warning + + This section is in progress, and is just copied from the old documentation. + +You can hide specific disks, temperature sensors, and networks by name in the config file via `disk_filter` and `mount_filter`, `temp_filter`, and `net_filter` respectively. Regex (`regex = true`), case-sensitivity (`case_sensitive = true`), and matching only if the entire word matches (`whole_word = true`) are supported, but are off by default. Filters default to denying entries that match and can be toggled by setting `is_list_ignored` to `false` in the config file. + +For example, here's the disk widget with no filter: + + + +The following in the config file would filter out some entries by disk name: + +```toml +[disk_filter] +is_list_ignored = true +list = ["/dev/sda"] +regex = true +case_sensitive = false +whole_word = false +``` + + + +If there are two potentially conflicting filters (i.e. when you are using both a disk and mount filter), the filter that explicitly allows an entry takes precedence over a filter that explicitly denies one. So for example, let's say I set a disk filter accepting anything with `/dev/sda`, but deny anything with `/mnt/.*` or `/`. So to do so, I write in the config file: + +```toml +[disk_filter] +is_list_ignored = false +list = ["/dev/sda"] +regex = true +case_sensitive = false +whole_word = false + +[mount_filter] +is_list_ignored = true +list = ["/mnt/.*", "/"] +regex = true +case_sensitive = false +whole_word = true +``` + +Which gives me: + + diff --git a/docs/content/configuration/config-file/default-config.md b/docs/content/configuration/config-file/default-config.md new file mode 100644 index 00000000..85fb3f42 --- /dev/null +++ b/docs/content/configuration/config-file/default-config.md @@ -0,0 +1,11 @@ +# Default Config + +A default config file is automatically generated at the following locations that bottom checks by default: + +| OS | Default Config Location | +| ------- | -------------------------------------------------------------------------------------------------------------------------------------- | +| macOS | `$HOME/Library/Application Support/bottom/bottom.toml`<br/> `~/.config/bottom/bottom.toml` <br/> `$XDG_CONFIG_HOME/bottom/bottom.toml` | +| Linux | `~/.config/bottom/bottom.toml` <br/> `$XDG_CONFIG_HOME/bottom/bottom.toml` | +| Windows | `C:\Users\<USER>\AppData\Roaming\bottom\bottom.toml` | + +Furthermore, if a custom config path that does not exist is given (using `-C` or `--config`), bottom will attempt to create a default config file at that location. diff --git a/docs/content/configuration/config-file/flags.md b/docs/content/configuration/config-file/flags.md new file mode 100644 index 00000000..e4896828 --- /dev/null +++ b/docs/content/configuration/config-file/flags.md @@ -0,0 +1,37 @@ +# Flags + +!!! Warning + + This section is in progress, and is just copied from the old documentation. + +Most of the [command line flags](../../command-line-flags) have config file equivalents to avoid having to type them out each time: + +| Field | Type | Functionality | +| ---------------------------- | ---------------------------------------------------------------------------------------------- | -------------------------------------------------------------- | +| `hide_avg_cpu` | Boolean | Hides the average CPU usage. | +| `dot_marker` | Boolean | Uses a dot marker for graphs. | +| `left_legend` | Boolean | Puts the CPU chart legend to the left side. | +| `current_usage` | Boolean | Sets process CPU% to be based on current CPU%. | +| `group_processes` | Boolean | Groups processes with the same name by default. | +| `case_sensitive` | Boolean | Enables case sensitivity by default. | +| `whole_word` | Boolean | Enables whole-word matching by default. | +| `regex` | Boolean | Enables regex by default. | +| `basic` | Boolean | Hides graphs and uses a more basic look. | +| `use_old_network_legend` | Boolean | DEPRECATED - uses the older network legend. | +| `battery` | Boolean | Shows the battery widget. | +| `rate` | Unsigned Int (represents milliseconds) | Sets a refresh rate in ms. | +| `default_time_value` | Unsigned Int (represents milliseconds) | Default time value for graphs in ms. | +| `time_delta` | Unsigned Int (represents milliseconds) | The amount in ms changed upon zooming. | +| `temperature_type` | String (one of ["k", "f", "c", "kelvin", "fahrenheit", "celsius"]) | Sets the temperature unit type. | +| `default_widget_type` | String (one of ["cpu", "proc", "net", "temp", "mem", "disk"], same as layout options) | Sets the default widget type, use --help for more info. | +| `default_widget_count` | Unsigned Int (represents which `default_widget_type`) | Sets the n'th selected widget type as the default. | +| `disable_click` | Boolean | Disables mouse clicks. | +| `color` | String (one of ["default", "default-light", "gruvbox", "gruvbox-light", "nord", "nord-light"]) | Use a color scheme, use --help for supported values. | +| `mem_as_value` | Boolean | Defaults to showing process memory usage by value. | +| `tree` | Boolean | Defaults to showing the process widget in tree mode. | +| `show_table_scroll_position` | Boolean | Shows the scroll position tracker in table widgets. | +| `process_command` | Boolean | Show processes as their commands by default. | +| `disable_advanced_kill` | Boolean | Hides advanced options to stop a process on Unix-like systems. | +| `network_use_binary_prefix` | Boolean | Displays the network widget with binary prefixes. | +| `network_use_bytes` | Boolean | Displays the network widget using bytes. | +| `network_use_log` | Boolean | Displays the network widget with a log scale. | diff --git a/docs/content/configuration/config-file/layout.md b/docs/content/configuration/config-file/layout.md new file mode 100644 index 00000000..fb32c5fe --- /dev/null +++ b/docs/content/configuration/config-file/layout.md @@ -0,0 +1,57 @@ +# Layout + +!!! Warning + + This section is in progress, and is just copied from the old documentation. + +bottom supports customizable layouts via the config file. Currently, layouts are controlled by using TOML objects and arrays. + +For example, given the sample layout: + +```toml +[[row]] + [[row.child]] + type="cpu" +[[row]] + ratio=2 + [[row.child]] + ratio=4 + type="mem" + [[row.child]] + ratio=3 + [[row.child.child]] + type="temp" + [[row.child.child]] + type="disk" +``` + +This would give a layout that has two rows, with a 1:2 ratio. The first row has only the CPU widget. +The second row is split into two columns with a 4:3 ratio. The first column contains the memory widget. +The second column is split into two rows with a 1:1 ratio. The first is the temperature widget, the second is the disk widget. + +This is what the layout would look like when run: + + + +Each `[[row]]` represents a _row_ in the layout. A row can have any number of `child` values. Each `[[row.child]]` +represents either a _column or a widget_. A column can have any number of `child` values as well. Each `[[row.child.child]]` +represents a _widget_. A widget is represented by having a `type` field set to a string. + +The following `type` values are supported: + +| | | +| -------------------------------- | ------------------------ | +| `"cpu"` | CPU chart and legend | +| `"mem", "memory"` | Memory chart | +| `"net", "network"` | Network chart and legend | +| `"proc", "process", "processes"` | Process table and search | +| `"temp", "temperature"` | Temperature table | +| `"disk"` | Disk table | +| `"empty"` | An empty space | +| `"batt", "battery"` | Battery statistics | + +Each component of the layout accepts a `ratio` value. If this is not set, it defaults to 1. + +Furthermore, you can have duplicate widgets. + +For an example, look at the [default config](https://github.com/ClementTsang/bottom/blob/master/sample_configs/default_config.toml), which contains the default layout. diff --git a/docs/content/configuration/config-file/theming.md b/docs/content/configuration/config-file/theming.md new file mode 100644 index 00000000..cbb46f85 --- /dev/null +++ b/docs/content/configuration/config-file/theming.md @@ -0,0 +1,31 @@ +# Theming + +!!! Warning + + This section is in progress, and is just copied from the old documentation. + +The config file can be used to set custom colours for parts of the application under the `[colors]` object. The following labels are customizable with strings that are hex colours, RGB colours, or specific named colours. + +Supported named colours are one of the following strings: `Reset, Black, Red, Green, Yellow, Blue, Magenta, Cyan, Gray, DarkGray, LightRed, LightGreen, LightYellow, LightBlue, LightMagenta, LightCyan, White`. + +| Labels | Details | Example | +| ------------------------------- | ------------------------------------------------------- | ------------------------------------------------------- | +| Table header colours | Colour of table headers | `table_header_color="255, 255, 255"` | +| CPU colour per core | Colour of each core. Read in order. | `cpu_core_colors=["#ffffff", "white", "255, 255, 255"]` | +| Average CPU colour | The average CPU color | `avg_cpu_color="White"` | +| All CPUs colour | The colour for the "All" CPU label | `all_cpu_color="White"` | +| RAM | The colour RAM will use | `ram_color="#ffffff"` | +| SWAP | The colour SWAP will use | `swap_color="#ffffff"` | +| RX | The colour rx will use | `rx_color="#ffffff"` | +| TX | The colour tx will use | `tx_color="#ffffff"` | +| Widget title colour | The colour of the label each widget has | `widget_title_color="#ffffff"` | +| Border colour | The colour of the border of unselected widgets | `border_color="#ffffff"` | +| Selected border colour | The colour of the border of selected widgets | `highlighted_border_color="#ffffff"` | +| Text colour | The colour of most text | `text_color="#ffffff"` | +| Graph colour | The colour of the lines and text of the graph | `graph_color="#ffffff"` | +| Cursor colour | The cursor's colour | `cursor_color="#ffffff"` | +| Selected text colour | The colour of text that is selected | `scroll_entry_text_color="#ffffff"` | +| Selected text background colour | The background colour of text that is selected | `scroll_entry_bg_color="#ffffff"` | +| High battery level colour | The colour used for a high battery level (100% to 50%) | `high_battery_color="green"` | +| Medium battery level colour | The colour used for a medium battery level (50% to 10%) | `medium_battery_color="yellow"` | +| Low battery level colour | The colour used for a low battery level (10% to 0%) | `low_battery_color="red"` | |