mirror of
https://github.com/ClementTsang/bottom.git
synced 2025-09-21 08:47:53 +02:00
docs: update docs page with missing features (#1805)
* add no key setting * do it here instead of in main loop * add a warning * docs: update a bunch of docs with features * linux-only test * oop * skip field check for other os * oop * easier way of doing it * use dead code * oop * huh guess I don't need it
This commit is contained in:
Clement Tsang
GitHub
parent
d799c656aa
commit
a35b81a187
@ -5,39 +5,43 @@ see information on these options by running `btm -h`, or run `btm --help` to dis
|
||||
|
||||
## General Options
|
||||
|
||||
| Option | Behaviour |
|
||||
| --------------------------------- | ---------------------------------------------------- |
|
||||
| `--autohide_time` | Temporarily shows the time scale in graphs. |
|
||||
| `-b, --basic` | Hides graphs and uses a more basic look. |
|
||||
| `-C, --config <CONFIG PATH>` | Sets the location of the config file. |
|
||||
| `-t, --default_time_value <TIME>` | Default time value for graphs. |
|
||||
| `--default_widget_count <N>` | Sets the N'th selected widget type as the default. |
|
||||
| `--default_widget_type <WIDGET>` | Sets the default widget type, use `--help` for info. |
|
||||
| `--disable_click` | Disables mouse clicks. |
|
||||
| `-m, --dot_marker` | Uses a dot marker for graphs. |
|
||||
| `-e, --expanded` | Expand the default widget upon starting the app. |
|
||||
| `--hide_table_gap` | Hides spacing between table headers and entries. |
|
||||
| `--hide_time` | Hides the time scale from being shown. |
|
||||
| `-r, --rate <TIME>` | Sets how often data is refreshed. |
|
||||
| `--retention <TIME>` | How far back data will be stored up to. |
|
||||
| `--show_table_scroll_position` | Shows the scroll position tracker in table widgets. |
|
||||
| `-d, --time_delta <TIME>` | The amount of time changed upon zooming. |
|
||||
| Option | Behaviour |
|
||||
| ----------------------------------- | ---------------------------------------------------------- |
|
||||
| `--autohide_time` | Temporarily shows the time scale in graphs. |
|
||||
| `-b`, `--basic` | Hides graphs and uses a more basic look. |
|
||||
| `-C`, `--config_location <PATH>` | Sets the location of the config file. |
|
||||
| `-t`, `--default_time_value <TIME>` | Default time value for graphs. |
|
||||
| `--default_widget_count <N>` | Sets the N'th selected widget type as the default. |
|
||||
| `--default_widget_type <WIDGET>` | Sets the default widget type. Use --help for more info. |
|
||||
| `--disable_click` | Disables mouse clicks. |
|
||||
| `--disable_keys` | Disables keyboard shortcuts, INCLUDING the ones that stop |
|
||||
| | bottom. |
|
||||
| `-m`, `--dot_marker` | Uses a dot marker for graphs. |
|
||||
| `-e`, `--expanded` | Expand the default widget upon starting the app. |
|
||||
| `--hide_table_gap` | Hides spacing between table headers and entries. |
|
||||
| `--hide_time` | Hides the time scale from being shown. |
|
||||
| `-r`, `--rate <TIME>` | Sets how often data is refreshed. |
|
||||
| `--retention <TIME>` | How far back data will be stored up to. |
|
||||
| `--show_table_scroll_position` | Shows the list scroll position tracker in the widget title |
|
||||
| | for table widgets. |
|
||||
| `-d`, `--time_delta <TIME>` | The amount of time changed upon zooming. |
|
||||
|
||||
## Process Options
|
||||
|
||||
| Option | Behaviour |
|
||||
| --------------------------- | --------------------------------------------------------------------------------------------- |
|
||||
| `-S, --case_sensitive` | Enables case sensitivity by default. |
|
||||
| `-u, --current_usage` | Calculates process CPU usage as a percentage of current usage rather than total usage. |
|
||||
| `--disable_advanced_kill` | Disable being able to send signals to processes. Only available on Linux, macOS, and FreeBSD. |
|
||||
| `-g, --group_processes` | Groups processes with the same name by default. No effect if `--tree` is set. |
|
||||
| `--process_memory_as_value` | Defaults to showing process memory usage by value. |
|
||||
| `--process_command` | Shows the full command name instead of the process name by default. |
|
||||
| `-R, --regex` | Enables regex by default while searching. |
|
||||
| `-T, --tree` | Makes the process widget use tree mode by default. |
|
||||
| `-n, --unnormalized_cpu` | Show process CPU% usage without averaging over the number of CPU cores. |
|
||||
| `-W, --whole_word` | Enables whole-word matching by default while searching. |
|
||||
| `--tree_collapse` | Collapse process tree by default. |
|
||||
| Option | Behaviour |
|
||||
| --------------------------- | -------------------------------------------------------------------------------------- |
|
||||
| `-S, --case_sensitive` | Enables case sensitivity by default when searching. |
|
||||
| `-u, --current_usage` | Calculates process CPU usage as a percentage of current usage rather than total usage. |
|
||||
| `--disable_advanced_kill` | Hides additional stopping options on Unix-like systems. |
|
||||
| `--get_threads` | Also gather process thread information. |
|
||||
| `-g, --group_processes` | Groups processes with the same name by default. No effect if `--tree` is set. |
|
||||
| `--process_memory_as_value` | Defaults to showing process memory usage by value. |
|
||||
| `--process_command` | Shows the full command name instead of the process name by default. |
|
||||
| `-R, --regex` | Enables regex by default while searching. |
|
||||
| `-T, --tree` | Makes the process widget use tree mode by default. |
|
||||
| `--tree_collapse` | Collapse process tree by default. |
|
||||
| `-n, --unnormalized_cpu` | Show process CPU% usage without averaging over the number of CPU cores. |
|
||||
| `-W, --whole_word` | Enables whole-word matching by default while searching. |
|
||||
|
||||
## Temperature Options
|
||||
|
||||
|
||||
37
docs/content/configuration/config-file/disk-table.md
Normal file
37
docs/content/configuration/config-file/disk-table.md
Normal file
@ -0,0 +1,37 @@
|
||||
# Disk Table
|
||||
|
||||
## Columns
|
||||
|
||||
You can configure which columns are shown by the disk table widget by setting the `columns` setting:
|
||||
|
||||
```toml
|
||||
[disk]
|
||||
# Pick which columns you want to use in any order.
|
||||
columns = ["Disk", "Mount", "Used", "Free", "Total", "Used%", "R/s", "W/s"]
|
||||
```
|
||||
|
||||
## Filtering Entries
|
||||
|
||||
You can filter out what entries to show by configuring `[disk.name_filter]` and `[disk.mount_filter]` to filter by name and mount point respectively. In particular,
|
||||
you can set a list of things to filter with by setting `list`, and configure how that list
|
||||
is processed with the other options.
|
||||
|
||||
For example, here we are ignoring any entry with a name that matches `/dev/sda<NUMBERS>`, or specifically `/dev/nvme0n1p2`.
|
||||
|
||||
```toml
|
||||
[disk.name_filter]
|
||||
# Whether to ignore any matches. Defaults to true.
|
||||
is_list_ignored = true
|
||||
|
||||
# A list of filters to try and match.
|
||||
list = ["/dev/sda\\d+", "/dev/nvme0n1p2"]
|
||||
|
||||
# Whether to use regex. Defaults to false.
|
||||
regex = true
|
||||
|
||||
# Whether to be case-sensitive. Defaults to false.
|
||||
case_sensitive = false
|
||||
|
||||
# Whether to be require matching the whole word. Defaults to false.
|
||||
whole_word = false
|
||||
```
|
||||
26
docs/content/configuration/config-file/network.md
Normal file
26
docs/content/configuration/config-file/network.md
Normal file
@ -0,0 +1,26 @@
|
||||
# Network
|
||||
|
||||
## Filtering Entries
|
||||
|
||||
You can filter out what entries to show by configuring `[network.interface_filter]` .
|
||||
In particular, you can set a list of things to filter with by setting `list`, and configure how that list is processed with the other options.
|
||||
|
||||
For example, here we are ignoring any entry with a name that matches `/dev/sda<NUMBERS>`, or specifically `/dev/nvme0n1p2`.
|
||||
|
||||
```toml
|
||||
[network.interface_filter]
|
||||
# Whether to ignore any matches. Defaults to true.
|
||||
is_list_ignored = true
|
||||
|
||||
# A list of filters to try and match.
|
||||
list = ["virbr0.*"]
|
||||
|
||||
# Whether to use regex. Defaults to false.
|
||||
regex = true
|
||||
|
||||
# Whether to be case-sensitive. Defaults to false.
|
||||
case_sensitive = false
|
||||
|
||||
# Whether to be require matching the whole word. Defaults to false.
|
||||
whole_word = false
|
||||
```
|
||||
@ -157,11 +157,12 @@ These can be set under `[styles.graphs]`:
|
||||
|
||||
These can be set under `[styles.widgets]`:
|
||||
|
||||
| Config field | Details | Examples |
|
||||
| ----------------------- | ------------------------------------------------------------ | --------------------------------------------------------------------- |
|
||||
| `border_color` | The colour of the widgets' borders | `border_color = "white"` |
|
||||
| `selected_border_color` | The colour of a widget's borders when the widget is selected | `selected_border_color = "white"` |
|
||||
| `widget_title` | Text styling for a widget's title | `widget_title = { color = "black", bg_color = "blue", bold = true }` |
|
||||
| `text` | Text styling for text in general | `text = { color = "black", bg_color = "blue", bold = true }` |
|
||||
| `selected_text` | Text styling for text when representing something that is selected | `selected_text = { color = "black", bg_color = "blue", bold = true }` |
|
||||
| `disabled_text` | Text styling for text when representing something that is disabled | `disabled_text = { color = "black", bg_color = "blue", bold = true }` |
|
||||
| Config field | Details | Examples |
|
||||
| ----------------------- | -------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
|
||||
| `border_color` | The colour of the widgets' borders | `border_color = "white"` |
|
||||
| `selected_border_color` | The colour of a widget's borders when the widget is selected | `selected_border_color = "white"` |
|
||||
| `widget_title` | Text styling for a widget's title | `widget_title = { color = "black", bg_color = "blue", bold = true }` |
|
||||
| `text` | Text styling for text in general | `text = { color = "black", bg_color = "blue", bold = true }` |
|
||||
| `selected_text` | Text styling for text when representing something that is selected | `selected_text = { color = "black", bg_color = "blue", bold = true }` |
|
||||
| `disabled_text` | Text styling for text when representing something that is disabled | `disabled_text = { color = "black", bg_color = "blue", bold = true }` |
|
||||
| `thread_text` | Text styling for text when representing process threads. Only usable on Linux at the moment. | `thread_text = { color = "green", bg_color = "blue", bold = true }` |
|
||||
|
||||
25
docs/content/configuration/config-file/temperature-table.md
Normal file
25
docs/content/configuration/config-file/temperature-table.md
Normal file
@ -0,0 +1,25 @@
|
||||
# Temperature Table
|
||||
|
||||
## Filtering Entries
|
||||
|
||||
You can filter out what entries to show by configuring `[temperature.sensor_filter]`. In particular you can set a list of things to filter with by setting `list`, and configure how that list is processed with the other options.
|
||||
|
||||
For example, here we are ignoring any sensor that has "cpu" or "wifi" in it.
|
||||
|
||||
```toml
|
||||
[temperature.sensor_filter]
|
||||
# Whether to ignore any matches. Defaults to true.
|
||||
is_list_ignored = true
|
||||
|
||||
# A list of filters to try and match.
|
||||
list = ["cpu", "wifi"]
|
||||
|
||||
# Whether to use regex. Defaults to false.
|
||||
regex = false
|
||||
|
||||
# Whether to be case-sensitive. Defaults to false.
|
||||
case_sensitive = false
|
||||
|
||||
# Whether to be require matching the whole word. Defaults to false.
|
||||
whole_word = false
|
||||
```
|
||||
@ -76,6 +76,9 @@
|
||||
# Disable mouse clicks
|
||||
#disable_click = false
|
||||
|
||||
# Disable keyboard shortcuts
|
||||
#disable_keys = false
|
||||
|
||||
# Show memory values in the processes widget as values by default
|
||||
#process_memory_as_value = false
|
||||
|
||||
@ -264,6 +267,9 @@
|
||||
#selected_text = {color = "black", bg_color = "light blue"}
|
||||
#disabled_text = {color = "dark gray"}
|
||||
|
||||
# Only on Linux
|
||||
#thread_text = {color = "green"}
|
||||
|
||||
# Layout - layouts follow a pattern like this:
|
||||
# [[row]] represents a row in the application.
|
||||
# [[row.child]] represents either a widget or a column.
|
||||
|
||||
@ -28,7 +28,7 @@
|
||||
"flags": {
|
||||
"anyOf": [
|
||||
{
|
||||
"$ref": "#/$defs/FlagConfig"
|
||||
"$ref": "#/$defs/GeneralConfig"
|
||||
},
|
||||
{
|
||||
"type": "null"
|
||||
@ -265,7 +265,7 @@
|
||||
"type"
|
||||
]
|
||||
},
|
||||
"FlagConfig": {
|
||||
"GeneralConfig": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"autohide_time": {
|
||||
@ -352,6 +352,12 @@
|
||||
"null"
|
||||
]
|
||||
},
|
||||
"disable_keys": {
|
||||
"type": [
|
||||
"boolean",
|
||||
"null"
|
||||
]
|
||||
},
|
||||
"dot_marker": {
|
||||
"type": [
|
||||
"boolean",
|
||||
@ -1047,6 +1053,17 @@
|
||||
}
|
||||
]
|
||||
},
|
||||
"thread_text": {
|
||||
"description": "Text styling for text when representing process threads. Only usable\n on Linux at the moment.",
|
||||
"anyOf": [
|
||||
{
|
||||
"$ref": "#/$defs/TextStyleConfig"
|
||||
},
|
||||
{
|
||||
"type": "null"
|
||||
}
|
||||
]
|
||||
},
|
||||
"widget_border_type": {
|
||||
"description": "Widget borders type.",
|
||||
"anyOf": [
|
||||
|
||||
@ -516,6 +516,9 @@ pub(crate) const CONFIG_TEXT: &str = r#"# This is a default config file for bott
|
||||
#selected_text = {color = "black", bg_color = "light blue"}
|
||||
#disabled_text = {color = "dark gray"}
|
||||
|
||||
# Only on Linux
|
||||
#thread_text = {color = "green"}
|
||||
|
||||
# Layout - layouts follow a pattern like this:
|
||||
# [[row]] represents a row in the application.
|
||||
# [[row.child]] represents either a widget or a column.
|
||||
|
||||
@ -210,8 +210,8 @@ pub struct GeneralArgs {
|
||||
#[arg(
|
||||
long,
|
||||
action = ArgAction::SetTrue,
|
||||
help = "Disables keypresses.",
|
||||
long_help = "Disables keypresses from interacting with bottom. Note this includes keyboard shortcuts to quit bottom.",
|
||||
help = "Disables keyboard shortcuts, INCLUDING the ones that stop bottom.",
|
||||
long_help = "Disables keyboard shortcuts from interacting with bottom. Note this includes keyboard shortcuts to quit bottom.",
|
||||
alias = "disable-keys"
|
||||
)]
|
||||
pub disable_keys: bool,
|
||||
@ -297,7 +297,7 @@ pub struct ProcessArgs {
|
||||
short = 'S',
|
||||
long,
|
||||
action = ArgAction::SetTrue,
|
||||
help = "Enables case sensitivity by default.",
|
||||
help = "Enables case sensitivity by default when searching.",
|
||||
long_help = "Enables case sensitivity by default when searching for a process.",
|
||||
alias = "case-sensitive"
|
||||
)]
|
||||
@ -317,8 +317,8 @@ pub struct ProcessArgs {
|
||||
#[arg(
|
||||
long,
|
||||
action = ArgAction::SetTrue,
|
||||
help = "Hides additional stopping options Unix-like systems.",
|
||||
long_help = "Hides additional stopping options Unix-like systems. Signal 15 (TERM) will be sent when \
|
||||
help = "Hides additional stopping options on Unix-like systems.",
|
||||
long_help = "Hides additional stopping options on Unix-like systems. Signal 15 (TERM) will be sent when \
|
||||
stopping a process.",
|
||||
alias = "disable-advanced-kill"
|
||||
)]
|
||||
@ -336,8 +336,8 @@ pub struct ProcessArgs {
|
||||
short = 'g',
|
||||
long,
|
||||
action = ArgAction::SetTrue,
|
||||
help = "Groups processes with the same name by default.",
|
||||
long_help = "Groups processes with the same name by default. Doesn't do anything if --tree is also set, or \
|
||||
help = "Groups processes with the same name by default when searching.",
|
||||
long_help = "Groups processes with the same name by default when searching. Doesn't do anything if --tree is also set, or \
|
||||
tree=true in the config.",
|
||||
alias = "group-processes"
|
||||
)]
|
||||
|
||||
@ -67,12 +67,16 @@ mod test {
|
||||
use super::Config;
|
||||
|
||||
for config_path in fs::read_dir("./tests/valid_configs").unwrap() {
|
||||
let config_path = config_path.unwrap();
|
||||
let config_path_str = config_path.path().display().to_string();
|
||||
let config_str = fs::read_to_string(config_path.path()).unwrap();
|
||||
let dir_entry = config_path.unwrap();
|
||||
let path = dir_entry.path();
|
||||
|
||||
toml_edit::de::from_str::<Config>(&config_str)
|
||||
.unwrap_or_else(|_| panic!("incorrectly rejected '{config_path_str}'"));
|
||||
if path.is_file() {
|
||||
let config_path_str = path.display().to_string();
|
||||
let config_str = fs::read_to_string(path).unwrap();
|
||||
|
||||
toml_edit::de::from_str::<Config>(&config_str)
|
||||
.unwrap_or_else(|_| panic!("incorrectly rejected '{config_path_str}'"));
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
@ -212,6 +212,11 @@ impl Styles {
|
||||
set_style!(self.selected_text_style, config.widgets, selected_text);
|
||||
set_style!(self.disabled_text_style, config.widgets, disabled_text);
|
||||
|
||||
#[cfg(target_os = "linux")]
|
||||
{
|
||||
set_style!(self.thread_text_style, config.widgets, thread_text);
|
||||
}
|
||||
|
||||
// Widget borders
|
||||
set_colour!(self.border_style, config.widgets, border_color);
|
||||
set_colour!(
|
||||
|
||||
@ -27,6 +27,10 @@ pub(crate) struct WidgetStyle {
|
||||
/// Text styling for text when representing something that is disabled.
|
||||
pub(crate) disabled_text: Option<TextStyleConfig>,
|
||||
|
||||
/// Text styling for text when representing process threads. Only usable
|
||||
/// on Linux at the moment.
|
||||
pub(crate) thread_text: Option<TextStyleConfig>,
|
||||
|
||||
/// Widget borders type.
|
||||
pub(crate) widget_border_type: Option<WidgetBorderType>,
|
||||
}
|
||||
|
||||
@ -189,3 +189,9 @@ fn test_filtering() {
|
||||
fn test_proc_columns() {
|
||||
run_and_kill(&["-C", "./tests/valid_configs/proc_columns.toml"]);
|
||||
}
|
||||
|
||||
#[cfg(target_os = "linux")]
|
||||
#[test]
|
||||
fn test_linux_only() {
|
||||
run_and_kill(&["-C", "./tests/valid_configs/os_specific/linux.toml"]);
|
||||
}
|
||||
|
||||
4
tests/valid_configs/os_specific/linux.toml
Normal file
4
tests/valid_configs/os_specific/linux.toml
Normal file
@ -0,0 +1,4 @@
|
||||
# Remove things from this if they are no longer OS-specific.
|
||||
|
||||
[styles.widgets]
|
||||
thread_text = { color = "green" }
|
||||
Loading…
x
Reference in New Issue
Block a user