diff options
| author | Clement Tsang <34804052+ClementTsang@users.noreply.github.com> | 2021-06-20 22:40:58 -0700 |
|---|---|---|
| committer | GitHub <noreply@github.com> | 2021-06-21 01:40:58 -0400 |
| commit | 06071d5abfb8b6715768e8bbb1236be49c02cf46 (patch) | |
| tree | 9a53c083eeabfce6d9f934598de97f787acf7123 /docs/content/configuration | |
| parent | a6f6df9ff833c0763e1ba191ff9d22a74bdb1fae (diff) | |
docs: migrate documentation over to mkdocs (#506)
A large migration of documentation over to mkdocs, and some rewrites. Some stuff (install information, basic supported systems, contributors, thanks) are still staying in README.md, and CONTRIBUTING.md is essentially duplicated right now. However, stuff like configuration and key/mouse bindings are now moved to mkdocs.
Some parts are still a bit WIP - it is definitely not done (documentation never seems to be...). However, it should be "good enough" for now, and I'm much happier working with the documentation in this form than trying to scroll through a giant endless README.md file. It also works much better for adding new documentation.
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"` | |