From 06071d5abfb8b6715768e8bbb1236be49c02cf46 Mon Sep 17 00:00:00 2001
From: Clement Tsang <34804052+ClementTsang@users.noreply.github.com>
Date: Sun, 20 Jun 2021 22:40:58 -0700
Subject: [PATCH] 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.
---
.github/ISSUE_TEMPLATE/bug_report.md | 62 +-
.github/ISSUE_TEMPLATE/feature_request.md | 9 +-
.github/ISSUE_TEMPLATE/packaging.md | 13 +
.github/ISSUE_TEMPLATE/packaging_template.md | 13 -
.../{question_template.md => questions.md} | 2 +-
.github/pull_request_template.md | 2 +-
.github/workflows/docs.yml | 27 +
.github/workflows/nightly.yml | 1 +
.gitignore | 3 +
CONTRIBUTING.md | 77 +-
FAQ.md | 18 -
README.md | 744 +++---------------
assets/and_or_search.png | Bin 29601 -> 0 bytes
assets/basic_mode.png | Bin 188084 -> 0 bytes
assets/battery.png | Bin 145634 -> 0 bytes
assets/cpu_filter.png | Bin 89220 -> 0 bytes
assets/cpu_layout.png | Bin 116559 -> 0 bytes
assets/or_search.png | Bin 53921 -> 0 bytes
assets/quote_search.png | Bin 190367 -> 0 bytes
assets/regex_search.png | Bin 95161 -> 0 bytes
assets/search_empty.png | Bin 173811 -> 0 bytes
assets/simple_search.png | Bin 46205 -> 0 bytes
assets/sort.png | Bin 239519 -> 0 bytes
assets/trees_1.png | Bin 312383 -> 0 bytes
assets/trees_2.png | Bin 195352 -> 0 bytes
assets/trees_3.png | Bin 47077 -> 0 bytes
assets/usage_search.png | Bin 35277 -> 0 bytes
docs/content/assets/screenshots/basic.png | Bin 0 -> 288598 bytes
docs/content/assets/screenshots/battery.png | Bin 0 -> 30717 bytes
.../disk-filtering}/disk_name_filter.png | Bin
.../disk_name_mount_filter.png | Bin
.../config/disk-filtering}/disk_no_filter.png | Bin
.../config/layout}/sample_layout.png | Bin
docs/content/assets/screenshots/cpu.png | Bin 0 -> 49968 bytes
docs/content/assets/screenshots/disk.png | Bin 0 -> 49886 bytes
docs/content/assets/screenshots/memory.png | Bin 0 -> 25819 bytes
.../assets/screenshots/network/network.png | Bin 0 -> 29912 bytes
.../screenshots/network/network_old.png | Bin 0 -> 172745 bytes
.../screenshots/process/process_default.png | Bin 0 -> 277755 bytes
.../screenshots/process/process_full.png | Bin 0 -> 260327 bytes
.../screenshots/process/process_grouped.png | Bin 0 -> 182950 bytes
.../screenshots/process/process_sort_menu.png | Bin 0 -> 295274 bytes
.../screenshots/process/process_tree.png | Bin 0 -> 292331 bytes
.../assets/screenshots/process/search/cpu.png | Bin 0 -> 51089 bytes
.../assets/screenshots/process/search/or.png | Bin 0 -> 99437 bytes
.../screenshots/process/search/quotes.png | Bin 0 -> 270188 bytes
.../screenshots/process/search/regex.png | Bin 0 -> 46953 bytes
.../screenshots/process/search/search.png | Bin 0 -> 40720 bytes
.../assets/screenshots/temperature.png | Bin 0 -> 55817 bytes
.../screenshots/troubleshooting/dots.png | Bin 0 -> 175366 bytes
.../troubleshooting/no_braille.png | Bin 0 -> 162476 bytes
.../troubleshooting/weird_braille.png | Bin 0 -> 60984 bytes
.../configuration/command-line-flags.md | 45 ++
.../config-file/data-filtering.md | 46 ++
.../config-file/default-config.md | 11 +
.../configuration/config-file/flags.md | 37 +
.../configuration/config-file/layout.md | 57 ++
.../configuration/config-file/theming.md | 31 +
docs/content/contribution/development.md | 11 +
docs/content/contribution/documentation.md | 29 +
.../contribution/issues-and-pull-requests.md | 25 +
.../packaging-and-distribution.md | 41 +
docs/content/index.md | 29 +
docs/content/stylesheets/extra.css | 12 +
docs/content/support.md | 42 +
docs/content/troubleshooting.md | 78 ++
docs/content/usage/basic-mode.md | 36 +
docs/content/usage/general-usage.md | 63 ++
docs/content/usage/widgets/battery.md | 35 +
docs/content/usage/widgets/cpu.md | 55 ++
docs/content/usage/widgets/disk.md | 36 +
docs/content/usage/widgets/memory.md | 30 +
docs/content/usage/widgets/network.md | 30 +
docs/content/usage/widgets/process.md | 227 ++++++
docs/content/usage/widgets/temperature.md | 28 +
docs/mkdocs.yml | 139 ++++
src/app.rs | 2 +
src/app/states.rs | 1 -
78 files changed, 1354 insertions(+), 793 deletions(-)
create mode 100644 .github/ISSUE_TEMPLATE/packaging.md
delete mode 100644 .github/ISSUE_TEMPLATE/packaging_template.md
rename .github/ISSUE_TEMPLATE/{question_template.md => questions.md} (54%)
create mode 100644 .github/workflows/docs.yml
delete mode 100644 FAQ.md
delete mode 100644 assets/and_or_search.png
delete mode 100644 assets/basic_mode.png
delete mode 100644 assets/battery.png
delete mode 100644 assets/cpu_filter.png
delete mode 100644 assets/cpu_layout.png
delete mode 100644 assets/or_search.png
delete mode 100644 assets/quote_search.png
delete mode 100644 assets/regex_search.png
delete mode 100644 assets/search_empty.png
delete mode 100644 assets/simple_search.png
delete mode 100644 assets/sort.png
delete mode 100644 assets/trees_1.png
delete mode 100644 assets/trees_2.png
delete mode 100644 assets/trees_3.png
delete mode 100644 assets/usage_search.png
create mode 100644 docs/content/assets/screenshots/basic.png
create mode 100644 docs/content/assets/screenshots/battery.png
rename {assets => docs/content/assets/screenshots/config/disk-filtering}/disk_name_filter.png (100%)
rename {assets => docs/content/assets/screenshots/config/disk-filtering}/disk_name_mount_filter.png (100%)
rename {assets => docs/content/assets/screenshots/config/disk-filtering}/disk_no_filter.png (100%)
rename {assets => docs/content/assets/screenshots/config/layout}/sample_layout.png (100%)
create mode 100644 docs/content/assets/screenshots/cpu.png
create mode 100644 docs/content/assets/screenshots/disk.png
create mode 100644 docs/content/assets/screenshots/memory.png
create mode 100644 docs/content/assets/screenshots/network/network.png
create mode 100644 docs/content/assets/screenshots/network/network_old.png
create mode 100644 docs/content/assets/screenshots/process/process_default.png
create mode 100644 docs/content/assets/screenshots/process/process_full.png
create mode 100644 docs/content/assets/screenshots/process/process_grouped.png
create mode 100644 docs/content/assets/screenshots/process/process_sort_menu.png
create mode 100644 docs/content/assets/screenshots/process/process_tree.png
create mode 100644 docs/content/assets/screenshots/process/search/cpu.png
create mode 100644 docs/content/assets/screenshots/process/search/or.png
create mode 100644 docs/content/assets/screenshots/process/search/quotes.png
create mode 100644 docs/content/assets/screenshots/process/search/regex.png
create mode 100644 docs/content/assets/screenshots/process/search/search.png
create mode 100644 docs/content/assets/screenshots/temperature.png
create mode 100644 docs/content/assets/screenshots/troubleshooting/dots.png
create mode 100644 docs/content/assets/screenshots/troubleshooting/no_braille.png
create mode 100644 docs/content/assets/screenshots/troubleshooting/weird_braille.png
create mode 100644 docs/content/configuration/command-line-flags.md
create mode 100644 docs/content/configuration/config-file/data-filtering.md
create mode 100644 docs/content/configuration/config-file/default-config.md
create mode 100644 docs/content/configuration/config-file/flags.md
create mode 100644 docs/content/configuration/config-file/layout.md
create mode 100644 docs/content/configuration/config-file/theming.md
create mode 100644 docs/content/contribution/development.md
create mode 100644 docs/content/contribution/documentation.md
create mode 100644 docs/content/contribution/issues-and-pull-requests.md
create mode 100644 docs/content/contribution/packaging-and-distribution.md
create mode 100644 docs/content/index.md
create mode 100644 docs/content/stylesheets/extra.css
create mode 100644 docs/content/support.md
create mode 100644 docs/content/troubleshooting.md
create mode 100644 docs/content/usage/basic-mode.md
create mode 100644 docs/content/usage/general-usage.md
create mode 100644 docs/content/usage/widgets/battery.md
create mode 100644 docs/content/usage/widgets/cpu.md
create mode 100644 docs/content/usage/widgets/disk.md
create mode 100644 docs/content/usage/widgets/memory.md
create mode 100644 docs/content/usage/widgets/network.md
create mode 100644 docs/content/usage/widgets/process.md
create mode 100644 docs/content/usage/widgets/temperature.md
create mode 100644 docs/mkdocs.yml
diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md
index d26baed5..b5548664 100644
--- a/.github/ISSUE_TEMPLATE/bug_report.md
+++ b/.github/ISSUE_TEMPLATE/bug_report.md
@@ -6,60 +6,40 @@ labels: "bug"
assignees: ""
---
+Before you report, please take a look at [Troubleshooting](https://clementtsang.github.io/bottom/troubleshooting) to see if there's already an answer to your problem.
+
+Also, **please fill in all fields if possible** - if the issue is too hard to reproduce or vague, it may not be fixed!
+
## Describe the bug
-_A clear and concise description of what the bug is and what the expected behaviour was. If applicable, add screenshots to help explain your problem:_
+Give a high level description of the bug.
-## How to reproduce
+## What operating system/architecture are you using?
-_Steps on how to reproduce the behaviour. Please try to include this section so I can reproduce your problem in order to fix it. If you are using any runtime flags (i.e. `btm --group`) please mention them as part of this.:_
+Please mention what operating system, version, and architecture you're experiencing the problem on (ex: macOS 10.13, x86_64). Please also ensure that your system is [on the list of supported systems](https://github.com/ClementTsang/bottom#support) - bug reports on unsupported systems are likely to be closed.
-## bottom version
+## What terminal are you using `bottom` on?
-_Use `btm -V` and report the version of bottom you have installed. Also, if you're not on the latest version, please [try that](https://github.com/ClementTsang/bottom/releases/latest) and see if the problem is already resolved._
+Please mention what terminal/terminal emulator you are using `bottom` on (ex: Konsole, Kitty).
-## bottom config file (if used)
+## What version are you on?
-_If you're using a config file, please include it in the report._
+Please ensure that the bug still exists on the [latest stable release](https://github.com/ClementTsang/bottom/releases/latest) or newer (i.e. nightly). If so, mention
+what version you are using here.
-## Installation method
+## How did you install `bottom`?
-_How did you install bottom? Note if it's not a supported method, I may not be able to help you._
+Please mention how you installed `bottom`. If you manually compiled it, please also mention your _Rust version_.
-## Platform and environment information
+## How can we reproduce this?
-### Operating system, OS version, and architecture
+Provide detailed steps on _how_ to reproduce your problem, to the best of your ability. Be as detailed as possible, and include config files or flags if relevant.
+If maintainers cannot reproduce the bug, it will be very hard to fix it.
-_Please specify your operating system, the version, and architecture, so I can try to replicate your environment as best as possible. Note that the officially supported platforms are:_
+## What is the actual behaviour?
-- _macOS (`x86_64`)_
-- _Linux (`x86_64`, `i686`, `aarch64`)_
-- _Windows (`x86_64`, `i686`)_
+What is the _actual_ result of the given steps? Be detailed. Please include screenshots if the issue is a visual one.
-_If your platform is not listed, please be aware I do not officially support it and may be unable to fix this issue._
+## What is the expected behaviour?
-### Terminal (i.e. urxvt, kitty, etc.)
-
-_Sometimes this matters, so please mention your terminal/terminal emulator._
-
-### Shell (i.e. zsh, bash, etc.)
-
-_Again, sometimes this matters, so please mention your shell type if possible._
-
-### Miscellaneous system info
-
-_Not totally necessary, but if possible, include details like:_
-
-_RAM size:_
-
-_SWAP size:_
-
-_CPU and number of cores:_
-
-### Rust version
-
-_Check this with `rustc --version`. This is only relevant if your version of bottom isn't from a pre-built binary (i.e. Cargo). Otherwise, feel free to skip._
-
-## Additional context
-
-_If anything hasn't been covered by the above categories, feel free to include it here:_
+What do you believe the expected behaviour should be given these steps?
diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md
index 49594883..827e2006 100644
--- a/.github/ISSUE_TEMPLATE/feature_request.md
+++ b/.github/ISSUE_TEMPLATE/feature_request.md
@@ -1,6 +1,6 @@
---
name: Feature request
-about: Got a good idea that hasn't already been mentioned? Suggest it!
+about: Got a good idea that hasn't already been suggested? Mention it here!
title: ""
labels: "feature"
assignees: ""
@@ -8,8 +8,5 @@ assignees: ""
### Describe the feature request
-_What is the feature of interest? Be clear and concise._
-
-### Additional context/details
-
-_Provide any additional context or details here. What needs to be done, why, etc:_
+Please describe what behaviour you are looking for, the motivation for it, and use cases for where this feature would be helpful.
+Try to be clear and concise - more details are usually helpful, but don't ramble on too much.
diff --git a/.github/ISSUE_TEMPLATE/packaging.md b/.github/ISSUE_TEMPLATE/packaging.md
new file mode 100644
index 00000000..3a13b560
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/packaging.md
@@ -0,0 +1,13 @@
+---
+name: Packaging
+about: For any issues, questions, or requests regarding packaging or distribution.
+title: ""
+labels: "packaging"
+assignees: ""
+---
+
+## Details
+
+What is the issue? Please be clear and concise.
+
+Note: if this issue is about supporting a new package manager/installation method, please do consider maintaining it yourself and sending in a PR, and I'll be glad accept it! See [the documentation](https://clementtsang.github.io/bottom/contribution/packaging-and-distribution/) for more information.
diff --git a/.github/ISSUE_TEMPLATE/packaging_template.md b/.github/ISSUE_TEMPLATE/packaging_template.md
deleted file mode 100644
index 9a657c69..00000000
--- a/.github/ISSUE_TEMPLATE/packaging_template.md
+++ /dev/null
@@ -1,13 +0,0 @@
----
-name: Packaging
-about: For any issues, questions, or requests regarding packaging or distribution.
-title: ""
-labels: "packaging"
-assignees: ""
----
-
-## Details
-
-_What is the issue? Please be clear and concise._
-
-_Note: if this issue is about supporting a new package manager, please do consider maintaining it yourself and sending in a PR, and I'll be glad accept it! While I definitely want to support more ways of distribution, it gets quite challenging to support package managers for operating systems you don't even have installed..._
diff --git a/.github/ISSUE_TEMPLATE/question_template.md b/.github/ISSUE_TEMPLATE/questions.md
similarity index 54%
rename from .github/ISSUE_TEMPLATE/question_template.md
rename to .github/ISSUE_TEMPLATE/questions.md
index 67578f08..8e908c0f 100644
--- a/.github/ISSUE_TEMPLATE/question_template.md
+++ b/.github/ISSUE_TEMPLATE/questions.md
@@ -8,4 +8,4 @@ assignees: ""
### Question
-_What do you want to ask in regards to this project? Note that if this is a feature request or a bug/issue report, please use the appropriate templates instead._
+What do you want to ask in regards to this project? Note that this is **not** the template to use if you have a bug report or feature request - use the appropriate templates instead.
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
index 16a03ae8..9d07b495 100644
--- a/.github/pull_request_template.md
+++ b/.github/pull_request_template.md
@@ -24,6 +24,6 @@ _If relevant, ensure the following have been met:_
- [ ] _Areas your change affects have been linted using rustfmt (`cargo fmt`)_
- [ ] _The change has been tested and doesn't appear to cause any unintended breakage_
-- [ ] _Documentation has been added/updated if needed (README, help menu, etc.)_
+- [ ] _Documentation has been added/updated if needed (`README.md`, help menu, etc.)_
- [ ] _The pull request passes the provided CI pipeline_
- [ ] _There are no merge conflicts_
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
new file mode 100644
index 00000000..67d6c829
--- /dev/null
+++ b/.github/workflows/docs.yml
@@ -0,0 +1,27 @@
+name: docs
+on:
+ workflow_dispatch:
+ # inputs:
+ # version:
+ # description: "The documentation version to update. Defaults to nightly."
+ # default: "nightly"
+ # required: false
+ push:
+ branches:
+ - master
+ paths:
+ - 'docs/**'
+ - '.github/workflows/docs.yml'
+jobs:
+ build-documentation:
+ name: Build and deploy docs
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v2
+ - uses: actions/setup-python@v2
+ with:
+ python-version: 3.x
+ - run: pip install mkdocs-material
+ - run: pip install mdx_truly_sane_lists
+ - run: cd docs/
+ - run: mkdocs gh-deploy --force
diff --git a/.github/workflows/nightly.yml b/.github/workflows/nightly.yml
index 4c642504..d78f4767 100644
--- a/.github/workflows/nightly.yml
+++ b/.github/workflows/nightly.yml
@@ -11,6 +11,7 @@ on:
isMock:
description: "Mock nightly run, fill in with anything to trigger a mock build."
default: ""
+ required: false
jobs:
create-github-release:
diff --git a/.gitignore b/.gitignore
index f08f998c..82cce855 100644
--- a/.gitignore
+++ b/.gitignore
@@ -31,3 +31,6 @@ deny.toml
# vscode
.vscode
+
+# mkdocs
+site/
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 01d3157e..0336185b 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,73 +1,30 @@
# Contribution
-If you want to contribute to this project - first of all, thank you! I'm glad to see interest in it!
+Contribution in any way is appreciated, whether it is reporting problems, fixing bugs, implementing features, improving the documentation, etc.
-Here are some notes about how to contribute to bottom (structure is based on the official
-[Rust contribution guidelines](https://github.com/rust-lang/rust/blob/master/CONTRIBUTING.md)):
+## Opening an issue
-- [Feature reports](#feature-reports)
-- [Bug reports](#bug-reports)
-- [Other types of reports](#other-types-of-reports)
-- [Pull requests](#pull-requests)
+### Bug reports
-## Feature reports
+When filing a bug report, please use the [bug report template](https://github.com/ClementTsang/bottom/issues/new?assignees=&labels=bug&template=bug_report.md&title=) and fill in as much as you can. It is _incredibly_ difficult for a maintainer to fix
+a bug when it cannot be reproduced, and giving as much detail as possible generally helps to make it easier to reproduce the problem!
-Feature suggestions can be submitted using the "feature" tag. Prior to submission, please look to see if this has already been suggested or solved; if it has and is not resolved, it would be better to comment on the relevant report.
+### Feature requests
-Within your feature report, try to answer the given prompts - in particular, state the specific feature you want and if possible, please state why you want this added to the program.
-
-## Bug reports
-
-Bug reports can be submitted using the "bug" tag. Prior to submission, please look to see if this has already been reported or solved; if it has and is not resolved, it would be better to comment on the relevant report.
-
-Within your bug report, try to answer the given prompts. Be as specific as possible - describe your bug to the best of your ability, how to replicate it, and provide information like screenshots, OS and terminal. It can be very useful to help whoever is dealing with the issue!
-
-## Other types of reports
-
-For reports/suggestions that don't fit the definition of a feature or bug, try to use the other tags:
-
-- `documentation`: If you note a typo, or want to suggest something to do with the documentation of bottom, use this.
-- `question`: If you have a question, and not really a suggestion or request, then use this tag.
-- `ci`, `investigative`, `refactoring`: Generally, these are for internal use to track issues in order to manage GitHub Projects, and won't be the appropriate topic for a report.
-- `other`: If your suggestion or issue doesn't fit those categories, then use this.
+Please use the [feature request template](https://github.com/ClementTsang/bottom/issues/new?assignees=&labels=feature&template=feature_request.md&title=) and fill it out. Remember to give details about what the feature is along with why you think this suggestion will be useful.
## Pull requests
-If you want to help contribute by submitting a PR, by all means, I'm open! In regards to the development process:
+The expected workflow for a pull request is:
-- I develop primarily using _stable_ Rust. That is, whatever is the most up-to-date stable version you can get via running
- `rustup update stable`.
+1. Fork the project.
+2. Make your changes.
+3. Make any documentation changes if necessary - if you add a new feature, it'll probably need documentation changes. See [here](./documentation.md) for tips on documentation.
+4. Commit and create a pull request to merge into the `master` branch. **Please follow the pull request template**.
+5. Wait for the tests to pass. These consist of clippy lints, rustfmt checks, and basic tests. **If you are a first time contributor, you may need to skip this step for now, as GitHub Actions requires approval to run.**
+6. Ask a maintainer to review your pull request. If changes are suggested or any comments are made, they should probably be addressed. Once it looks good, it'll be merged!
-- There are some tests, they're mostly for sanity checks. Please run `cargo test` to ensure you didn't break anything important, unless the change will break the test (in which case please amend the tests).
+## Further reading
- - Note that `cargo test` will fail on anything lower than 1.43.0 due to it using a then-introduced env variable.
-
-- I use both [clippy](https://github.com/rust-lang/rust-clippy) and [rustfmt](https://github.com/rust-lang/rustfmt) in development (with some settings, see [clippy.toml](./clippy.toml) and [rustfmt.toml](rustfmt.toml)). Note clippy must pass to for PRs to be accepted.
-
- - You can check clippy using `cargo clippy`.
-
- - I use [cargo-husky](https://github.com/rhysd/cargo-husky) to automatically run a `cargo clippy` check.
-
-- You may notice that I have fern and log as dependencies; this is mostly for easy debugging via the `debug!()` macro. It writes to the `debug.log` file that will automatically be created if you run in debug mode (so `cargo run`).
-
-And in regards to the pull request process:
-
-- Create a personal fork of the process and PR that, as per the [fork and pull method](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/about-collaborative-development-models).
-
-- Merge against the `master` branch.
-
-- If you encounter a merge conflict, I expect you to resolve this via rebasing to `master`.
-
-- _Ensure your change builds, runs, and works_. Furthermore, state how you checked this, including what platforms you tested on.
-
-- If your change will result in needing to update documentation, please do so. In particular:
-
- - Does the README need to be updated to accommodate your change?
-
- - Does the help action, `?`, need to be updated to accommodate your change?
-
-- Please ensure that CI passes. If it fails, check to see why it fails! Chances are it's clippy.
-
-- If all looks good, then request someone with write access (so basically me, [@ClementTsang](https://github.com/ClementTsang)) to give your code a review. If it's fine, then I'll merge!
-
-- Please use the [pull request template](https://github.com/ClementTsang/bottom/blob/master/.github/pull_request_template.md) to help you.
+- For details on contributing to documentation, see [here](https://clementtsang.github.io/bottom/contribution/documentation/).
+- For details on packaging and distribution, see [here](https://clementtsang.github.io/bottom/contribution/packaging-and-distribution/).
diff --git a/FAQ.md b/FAQ.md
deleted file mode 100644
index 8edc6858..00000000
--- a/FAQ.md
+++ /dev/null
@@ -1,18 +0,0 @@
-# FAQ
-
-- [My graphs look kinda weird with some extra dots, how do I fix this?](#braille-support)
-
-
-My graphs look kinda weird with some extra dots, how do I fix this?
-
-
-
-
-You'll have to make sure you have proper braille font support. For example, for Arch, you may have to
-install ttf-ubraille and/or properly set it up for your terminal.
-
-- [Why can't I see all my processes/process usage on macOS?]
-
-You may have to run the program with elevated privileges - i.e. `sudo btm`. If you don't like doing
-this repeatedly, you can manually force it to run with root each time - for example, following
-[this related guide from the htop wiki](https://github.com/hishamhm/htop/wiki/macOS:-run-without-sudo).
diff --git a/README.md b/README.md
index ba98983d..5c696a87 100644
--- a/README.md
+++ b/README.md
@@ -1,137 +1,69 @@
# bottom
-
-[](https://crates.io/crates/bottom)
+[](https://github.com/ClementTsang/bottom/actions?query=branch%3Amaster)
+[](https://crates.io/crates/bottom)
+[](https://clementtsang.github.io/bottom)
A cross-platform graphical process/system monitor with a customizable interface and a multitude of features. Supports Linux, macOS, and Windows. Inspired by [gtop](https://github.com/aksakalli/gtop), [gotop](https://github.com/xxxserxxx/gotop), and [htop](https://github.com/htop-dev/htop/).
- _Theme based on [gruvbox](https://github.com/morhetz/gruvbox)_ (`--color gruvbox`). _Font is [IBM Plex Mono](https://www.ibm.com/plex/), terminal is [Kitty](https://sw.kovidgoyal.net/kitty/)._
+
+
+
+
-**Note**: If you are reading this on the master branch, then it may refer to in-development or un-released features/changes. Please refer to [release branch](https://github.com/ClementTsang/bottom/tree/release/README.md) or [crates.io](https://crates.io/crates/bottom) for the most up-to-date _release_ documentation.
+## Features
-## Table of Contents
+As (yet another) process/system visualization and management application, bottom supports the typical features:
-- [Support](#support)
- - [Compatibility](#compatibility)
- - [Other known platform-specific issues](#other-known-platform-specific-issues)
-- [Installation](#installation)
- - [Manually](#manually)
- - [Nightly](#nightly)
- - [Cargo](#cargo)
- - [AUR](#aur)
- - [Debian](#debian)
- - [Fedora/CentOS](#fedoracentos)
- - [Gentoo](#gentoo)
- - [Nix](#nix)
- - [Solus](#solus)
- - [MacPorts](#macports)
- - [Homebrew](#homebrew)
- - [Scoop](#scoop)
- - [Chocolatey](#chocolatey)
- - [winget](#winget)
- - [Auto-completion](#auto-completion)
-- [Usage](#usage)
- - [Flags](#flags)
- - [Keybindings](#keybindings)
- - [General](#general)
- - [Process bindings](#process-bindings)
- - [Process search bindings](#process-search-bindings)
- - [Process sort bindings](#process-sort-bindings)
- - [Battery bindings](#battery-bindings)
- - [Basic memory bindings](#basic-memory-bindings)
- - [Process searching keywords](#process-searching-keywords)
- - [Supported search types](#supported-search-types)
- - [Supported comparison operators](#supported-comparison-operators)
- - [Supported logical operators](#supported-logical-operators)
- - [Supported units](#supported-units)
- - [Other syntax](#other-syntax)
- - [Mousebindings](#mousebindings)
- - [General](#general-1)
- - [CPU bindings](#cpu-bindings)
- - [Process bindings](#process-bindings-1)
-- [Features](#features)
- - [Processes](#processes)
- - [Process searching](#process-searching)
- - [Process sorting](#process-sorting)
- - [Tree mode](#tree-mode)
- - [Zoom](#zoom)
- - [Expand](#expand)
- - [Basic mode](#basic-mode)
- - [Config files](#config-files)
- - [Config flags](#config-flags)
- - [Theming](#theming)
- - [Layout](#layout)
- - [Disk, temperature, and network filtering](#disk-temperature-and-network-filtering)
- - [Battery](#battery)
-- [FAQ](#faq)
-- [Contribution](#contribution)
- - [Contributors](#contributors)
-- [Thanks](#thanks)
+- Graphical visualization widgets for:
+
+ - CPU usage over time, at an average and per-core level
+ - RAM and swap usage over time
+ - Network I/O usage over time
+
+ with support for zooming in/out the current time interval displayed.
+
+- Widgets for displaying info about disk capacity/usage, temperature sensors, and battery.
+
+- A widget for displaying, sorting, and searching info about processes, as well as support for:
+
+ - Kill signals
+ - Tree mode
+
+- Cross-platform support for Linux, macOS, and Windows, with more planned in the future.
+
+- Customizable behaviour that can be controlled with command-line flags or a config file, such as:
+
+ - Custom and pre-built colour themes
+ - Changing the default behaviour of some widgets
+ - Changing the layout of widgets
+ - Filtering out entries in disk and temperature widgets
+
+- And some other nice stuff, like:
+ - An htop-inspired basic mode
+ - Expanding widgets of interest
+
+You can find more details in [the documentation](https://clementtsang.github.io/bottom/usage/general-usage/).
## Support
-Note that bottom is:
+bottom _officially_ supports the following operating systems and corresponding architectures:
-- Built and released using the most recent stable version of Rust
-- Officially supports:
- - macOS (`x86_64`)
- - Linux (`x86_64`, `i686`, `aarch64`)
- - Windows (`x86_64`, `i686`)
+- macOS (`x86_64`)
+- Linux (`x86_64`, `i686`, `aarch64`)
+- Windows (`x86_64`, `i686`)
-Operating systems, versions of Rust, or platforms that are outside of this list are
-_not_ currently officially supported - even if it is built, tested, or works - and I may not be
-able to fix bugs for these!
+These platforms are tested to work for the most part and issues on these platforms will be fixed if possible.
+Furthermore, binaries are expected to be built and tested using the most recent version of stable Rust.
-### Compatibility
-
-The current compatibility of widgets with operating systems from personal testing:
-
-| OS | CPU | Memory | Disks | Temperature | Processes/Search | Networks | Battery |
-| ------- | --- | ------ | ----- | ------------------------------------ | ------------------------------------------ | -------- | -------------------------------------------- |
-| Linux | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
-| Windows | ✓ | ✓ | ✓ | ? (seems to require elevated access) | ✓ | ✓ | ✓ (seems to have issues with dual batteries) |
-| macOS | ✓ | ✓ | ✓ | ✓ | ✓ (requires `sudo btm` to show everything) | ✓ | ✓ |
-
-### Other known platform-specific issues
-
-- M1-based macOS devices may have issues with temperature sensors not returning anything.
-
-- For now, WSL has an issue reporting total memory usage.
-
-- WSL and WSL2 (as far as I know) cannot correctly report temperature sensors.
-
-- WSL2 will not match Windows' own Task Manager, this appears to be due to how WSL2 works.
+For more details on known problems and unsupported platforms, feel free to check out [the documentation page on support](https://clementtsang.github.io/bottom/support).
## Installation
-### Manually
-
-There are a few ways to go about doing this manually. If you do so, please build using the current stable release of Rust. For example:
-
-```bash
-# If required, update Rust on the stable channel
-rustup update stable
-
-# Clone and install the newest master version all via Cargo
-cargo install --git https://github.com/ClementTsang/bottom
-
-# Clone from master and install manually
-git clone https://github.com/ClementTsang/bottom
-cd bottom
-cargo install --path .
-
-# Download from releases and install
-curl -LO https://github.com/ClementTsang/bottom/archive/0.6.1.tar.gz
-tar -xzvf 0.6.1.tar.gz
-cargo install --path .
-```
-
-Or, you can just download the binary from the [latest release](https://github.com/ClementTsang/bottom/releases/latest).
-
-### Nightly
-
-You can install pre-release nightly versions [here](https://github.com/ClementTsang/bottom/releases/tag/nightly). Builds are generated every day at 00:00 UTC, based on the most recent commit on the master branch.
-
### Cargo
```bash
@@ -146,7 +78,7 @@ cargo install bottom --locked
### AUR
-Normal package found [here](https://aur.archlinux.org/packages/bottom/), binary package found [here](https://aur.archlinux.org/packages/bottom-bin/):
+The normal package can be found [here](https://aur.archlinux.org/packages/bottom/), while the binary package found [here](https://aur.archlinux.org/packages/bottom-bin/):
```bash
yay -S bottom
@@ -175,7 +107,7 @@ sudo dnf install bottom
### Gentoo
-Available in [GURU](https://wiki.gentoo.org/wiki/Project:GURU) and [dm9pZCAq](https://github.com/gentoo-mirror/dm9pZCAq) overlays
+Available in [GURU](https://wiki.gentoo.org/wiki/Project:GURU) and [dm9pZCAq](https://github.com/gentoo-mirror/dm9pZCAq) overlays:
```bash
sudo eselect repository enable guru
@@ -235,7 +167,7 @@ Since validation of the package takes time, it may take a while to become availa
```bash
choco install bottom
-# Version number may be required for newer releases, if available:
+# The version number may be required for newer releases during the approval process:
choco install bottom --version=0.6.1
```
@@ -251,12 +183,38 @@ winget install bottom
You can also manually do the same thing by going to the [latest release](https://github.com/ClementTsang/bottom/releases/latest)
and installing via the `.msi` file.
-You can uninstall via Control Panel or Options in Windows.
+You can uninstall via Control Panel, Options, or `winget --uninstall bottom`.
-### Auto-completion
+### Building
-Shell completions are included in binary releases, and are generated in the same directory as the
-binary if bottom is manually built.
+There are a few ways to go about doing this manually. Note that in all cases, you would want to build using the most recent version of stable Rust:
+
+```bash
+# If required, update Rust on the stable channel
+rustup update stable
+
+# Download from releases and install
+curl -LO https://github.com/ClementTsang/bottom/archive/0.6.1.tar.gz
+tar -xzvf 0.6.1.tar.gz
+cargo install --path .
+
+# Clone from master and install manually
+git clone https://github.com/ClementTsang/bottom
+cd bottom
+cargo install --path .
+
+# Clone and install the newest master version all via Cargo
+cargo install --git https://github.com/ClementTsang/bottom
+```
+
+### Binaries
+
+You can also try to use the generated release binaries and manually install them:
+
+- [Latest stable release](https://github.com/ClementTsang/bottom/releases/latest), generated off of the release branch
+- [Latest nightly version](https://github.com/ClementTsang/bottom/releases/tag/nightly), which is generated daily off of the master branch at 00:00 UTC
+
+The release binaries are packaged with shell auto-completion files for bash, fish, zsh, and Powershell. To install them:
- For bash, move `btm.bash` to `$XDG_CONFIG_HOME/bash_completion or /etc/bash_completion.d/`.
- For fish, move `btm.fish` to `$HOME/.config/fish/completions/`.
@@ -264,541 +222,23 @@ binary if bottom is manually built.
- For PowerShell, add `. _btm.ps1` to your PowerShell
[profile]().
-Some install scripts (i.e. AUR) will automatically do this for you.
-
## Usage
-Run using `btm`.
+You can run bottom using `btm`.
-### Flags
+For help on flags, use `btm -h` for a quick overview or `btm --help` for more details.
-Use `btm --help` for more information.
+## Configuration
-```
- --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 Use a color scheme, use --help for supported values.
- -C, --config Sets the location of the config file.
- -u, --current_usage Sets process CPU% to be based on current CPU%.
- -t, --default_time_value Default time value for graphs in ms.
- --default_widget_count Sets the n'th selected widget type as the default.
- --default_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 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 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.
-```
+bottom accepts a number of command-line arguments to change the behaviour of the application as desired. Additionally, bottom will automatically
+generate a configuration file on the first launch, which one can change as appropriate.
-### Keybindings
-
-#### General
-
-| | |
-| ------------------------------------------- | ------------------------------------------------------------ |
-| `q`, `Ctrl-c` | Quit |
-| `Esc` | Close dialog windows, search, widgets, or exit expanded mode |
-| `Ctrl-r` | Reset display and any collected data |
-| `f` | Freeze/unfreeze updating with new data |
-| `Ctrl-Left` `Shift-Left` `H` `A` | Move widget selection left |
-| `Ctrl-Right` `Shift-Right` `L` `D` | Move widget selection right |
-| `Ctrl-Up` `Shift-Up` `K` `W` | Move widget selection up |
-| `Ctrl-Down` `Shift-Down` `J` `S` | Move widget selection down |
-| `Left`, `h` | Move left within widget |
-| `Down`, `j` | Move down within widget |
-| `Up`,`k` | Move up within widget |
-| `Right`, `l` | Move right within widget |
-| `?` | Open help menu |
-| `gg`, `Home` | Jump to the first entry |
-| `Shift-g`, `End` | Jump to the last entry |
-| `e` | Toggle expanding the currently selected widget |
-| `+` | Zoom in on chart (decrease time range) |
-| `-` | Zoom out on chart (increase time range) |
-| `=` | Reset zoom |
-
-#### Process bindings
-
-| | |
-| ------------- | ---------------------------------------------------------------- |
-| `dd` | Kill the selected process |
-| `c` | Sort by CPU usage, press again to reverse sorting order |
-| `m` | Sort by memory usage, press again to reverse sorting order |
-| `p` | Sort by PID name, press again to reverse sorting order |
-| `n` | Sort by process name, press again to reverse sorting order |
-| `Tab` | Group/un-group processes with the same name |
-| `Ctrl-f`, `/` | Open process search widget |
-| `P` | Toggle between showing the full command or just the process name |
-| `s, F6` | Open process sort widget |
-| `I` | Invert current sort |
-| `%` | Toggle between values and percentages for memory usage |
-| `t`, `F5` | Toggle tree mode |
-
-#### Process search bindings
-
-| | |
-| ------------- | -------------------------------------------- |
-| `Tab` | Toggle between searching by PID or name |
-| `Esc` | Close the search widget (retains the filter) |
-| `Ctrl-a` | Skip to the start of the search query |
-| `Ctrl-e` | Skip to the end of the search query |
-| `Ctrl-u` | Clear the current search query |
-| `Ctrl-w` | Delete a word behind the cursor |
-| `Ctrl-h` | Delete the character behind the cursor |
-| `Backspace` | Delete the character behind the cursor |
-| `Delete` | Delete the character at the cursor |
-| `Alt-c`, `F1` | Toggle matching case |
-| `Alt-w`, `F2` | Toggle matching the entire word |
-| `Alt-r`, `F3` | Toggle using regex |
-| `Left` | Move cursor left |
-| `Right` | Move cursor right |
-
-### Process sort bindings
-
-| | |
-| -------------- | ------------------------------- |
-| `Down`, `j` | Scroll down in list |
-| `Up`, `k` | Scroll up in list |
-| `Mouse scroll` | Scroll through sort widget |
-| `Esc` | Close the sort widget |
-| `Enter` | Sort by current selected column |
-
-#### Battery bindings
-
-| | |
-| -------------- | -------------------------- |
-| `Left, Alt-h` | Go to the next battery |
-| `Right, Alt-l` | Go to the previous battery |
-
-#### Basic memory bindings
-
-| | |
-| --- | ------------------------------------------------------ |
-| `%` | Toggle between values and percentages for memory usage |
-
-### Process searching keywords
-
-- None of the keywords are case sensitive.
-- Use brackets to logically group together parts of the search.
-- Furthermore, if you want to search a reserved keyword, surround the text in quotes - for example, `"or" or "(sd-pam)"` would be a valid search:
-
-
-
-#### Supported search types
-
-| Keywords | Example | Description |
-| ------------------- | ------------------ | ------------------------------------------------------------------------------- |
-| | `btm` | Matches by process or command name; supports regex |
-| `pid` | `pid=1044` | Matches by PID; supports regex |
-| `cpu`, `cpu%` | `cpu > 0.5` | Matches the CPU column; supports comparison operators |
-| `memb` | `memb > 1000 b` | Matches the memory column in terms of bytes; supports comparison operators |
-| `mem`, `mem%` | `mem < 0.5` | Matches the memory column in terms of percent; supports comparison operators |
-| `read`, `r/s` | `read = 1 mb` | Matches the read/s column in terms of bytes; supports comparison operators |
-| `write`, `w/s` | `write >= 1 kb` | Matches the write/s column in terms of bytes; supports comparison operators |
-| `tread`, `t.read` | `tread <= 1024 gb` | Matches he total read column in terms of bytes; supports comparison operators |
-| `twrite`, `t.write` | `twrite > 1024 tb` | Matches the total write column in terms of bytes; supports comparison operators |
-| `user` | `user=root` | Matches by user; supports regex |
-| `state` | `state=running` | Matches by state; supports regex |
-
-#### Supported comparison operators
-
-| Keywords | Description |
-| -------- | -------------------------------------------------------------- |
-| `=` | Checks if the values are equal |
-| `>` | Checks if the left value is strictly greater than the right |
-| `<` | Checks if the left value is strictly less than the right |
-| `>=` | Checks if the left value is greater than or equal to the right |
-| `<=` | Checks if the left value is less than or equal to the right |
-
-#### Supported logical operators
-
-Note that the `and` operator takes precedence over the `or` operator.
-
-| Keywords | Usage | Description |
-| ------------------ | -------------------------------------------- | --------------------------------------------------- |
-| `and, &&, ` | ` and/&&/` | Requires both conditions to be true to match |
-| `or, \|\|` | ` or/\|\| ` | Requires at least one condition to be true to match |
-
-#### Supported units
-
-| Keywords | Description |
-| -------- | ----------- |
-| `B` | Bytes |
-| `KB` | Kilobytes |
-| `MB` | Megabytes |
-| `GB` | Gigabytes |
-| `TB` | Terabytes |
-| `KiB` | Kibibytes |
-| `MiB` | Mebibytes |
-| `GiB` | Gibibytes |
-| `TiB` | Tebibytes |
-
-#### Other syntax
-
-| Keywords | Usage | Description |
-| -------- | ---------------------------------------------------- | -------------------------- |
-| `()` | `( AND ) OR ` | Group together a condition |
-
-### Mousebindings
-
-#### General
-
-| | |
-| ------ | ----------------------------------------------------------------------------------------------------- |
-| Scroll | Table: Scroll Chart: Zooms in or out by scrolling up or down respectively |
-| Click | Selects the clicked widget, table entry, dialog option, or tab. Can be disabled via options/flags. |
-
-#### CPU bindings
-
-| | |
-| ------ | --------------------------------------------------------------------- |
-| Scroll | Scrolling over an CPU core/average shows only that entry on the chart |
-
-#### Process bindings
-
-| | |
-| ---------------------- | --------------------------------------------------------------------------------------------------- |
-| Click on process entry | If in tree mode and you click on a selected entry, it toggles whether the branch is expanded or not |
-| Click on table header | Sorts the widget by that column, or inverts the sort if already selected |
-
-## Features
-
-As yet _another_ process/system visualization and management application, bottom supports the typical features:
-
-- CPU usage visualization, on an average and per-core basis
-
-- RAM and swap usage visualization
-
-- Network visualization for receiving and transmitting
-
-- Display information about disk capacity and I/O per second
-
-- Display temperatures from sensors
-
-- Display information regarding processes, like CPU, memory, I/O usage, user, and process state
-
-- Process management (well, if process killing is all you need)
-
-It also aims to be:
-
-- Lightweight
-
-- Cross-platform - supports 64-bit Linux, Windows, and macOS
-
-In addition, bottom also currently has the following features:
-
-### Processes
-
-#### Process searching
-
-On any process widget, hit `/` to bring up a search bar. If the layout has multiple process widgets, note this search is independent of other widgets.
-
-
-
-By default, just typing in something will search by process name:
-
-
-
-This simple search can be refined by matching by case, matching the entire word, or by using regex:
-
-
-
-Now let's say you want to search for two things - luckily, we have the `AND` and `OR` logical operators:
-
-
-
-
-
-Furthermore, one is able to refine their searches by CPU usage, memory usage, PID, and more. For example:
-
-
-
-You can see all available keywords and query options [here](#process-searching-keywords).
-
-#### Process sorting
-
-You can sort the processes list by any column you want by pressing `s` while on a process widget:
-
-
-
-#### Tree mode
-
-Use `t` or `F5` to toggle tree mode in a process widget. This is somewhat similar to htop's tree
-mode.
-
-
-
-Sorting works as well, but it is done per groups of siblings. For example, by CPU%:
-
-
-
-You can also still filter processes. Branches that entirely do not match the query are pruned out,
-but if a branch contains an element that does match the query, any non-matching elements will instead
-just be greyed out, so the tree structure is still maintained:
-
-
-
-### Zoom
-
-Using the `+`/`-` keys or the scroll wheel will move the current time intervals of the currently selected widget, and `=` to reset the zoom levels to the default.
-Widgets can hold different time intervals independently. These time intervals can be adjusted using the
-`-t`/`--default_time_value` and `-d`/`--time_delta` options, or their corresponding config options.
-
-### Expand
-
-Only care about one specific widget? You can go to that widget and hit `e` to make that widget expand and take
-up the entire drawing area. You can minimize this expanded widget with `Esc` or pressing `e` again.
-
-### Basic mode
-
-Using the `-b` or `--basic_mode` (or their corresponding config options) will open bottom in basic mode.
-There are no charts or expanded mode when using this, and tables are condensed such that only one table is displayed
-at a time.
-
-
-
-Note custom layouts are currently not available when this is used.
-
-### Config files
-
-bottom supports reading from a config file to customize its behaviour and look.
-By default, bottom will look at (based on [dirs](https://github.com/dirs-dev/dirs-rs#features)):
-
-| OS | Location |
-| ----------------------------------------------------------------------- | -------- |
-| `~/.config/bottom/bottom.toml` or `$XDG_CONFIG_HOME/bottom/bottom.toml` | Linux/macOS |
-| `$HOME/Library/Application Support/bottom/bottom.toml` | macOS |
-| `C:\Users\\AppData\Roaming\bottom\bottom.toml` | Windows |
-
-Note that if a config file does not exist at either the default location or the passed in location via `-C` or `--config`, one is automatically created with no settings applied.
-
-#### Config flags
-
-The following options can be set under `[flags]` to achieve the same effect as passing in a flag on runtime. Note that if a flag is given, it will override the config file.
-
-These are the following supported flag config values, which correspond to the flag of the same name described in [Flags](#flags):
-
-| 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. |
-
-#### Theming
-
-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"` |
-
-#### Layout
-
-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.
-
-For an example, look at the [default config](./sample_configs/default_config.toml), which contains the default layout.
-
-Furthermore, you can have duplicate widgets. This means you could do something like:
-
-```toml
-[[row]]
- ratio=1
- [[row.child]]
- type="cpu"
- [[row.child]]
- type="cpu"
- [[row.child]]
- type="cpu"
-[[row]]
- ratio=1
- [[row.child]]
- type="cpu"
- [[row.child]]
- type="empty"
- [[row.child]]
- type="cpu"
-[[row]]
- ratio=1
- [[row.child]]
- type="cpu"
- [[row.child]]
- type="cpu"
- [[row.child]]
- type="cpu"
-```
-
-and get the following CPU donut:
-
-
-#### Disk, temperature, and network filtering
-
-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:
-
-
-
-### Battery
-
-You can get battery statistics (charge, time to fill/discharge, consumption in watts, and battery health) via the battery widget.
-
-Since this is only useful for devices like laptops, it is off by default. You can either enable the widget in the default layout via the `--battery` flag, or by specifying the widget in a [layout](#layout):
-
-
-
-## FAQ
-
-Please see the [FAQ](./FAQ.md) for answers to frequently asked questions.
+More details on configuration can be found [in the documentation](https://clementtsang.github.io/bottom/configuration/config-file/default-config/).
## Contribution
-Contribution is always welcome! Please take a look at [CONTRIBUTING.md](./CONTRIBUTING.md) for details on how to help.
+Whether it's reporting problems, documentation, or code, contribution is always welcome! Please read
+[CONTRIBUTING.md](./CONTRIBUTING.md) for details on how to contribute to bottom.
### Contributors
@@ -841,10 +281,10 @@ Thanks to all contributors ([emoji key](https://allcontributors.org/docs/en/emoj
## Thanks
- This project is very much inspired by [gotop](https://github.com/xxxserxxx/gotop),
- [ytop](https://github.com/cjbassi/ytop), [gtop](https://github.com/aksakalli/gtop), and [htop](https://github.com/htop-dev/htop/).
+ [gtop](https://github.com/aksakalli/gtop), and [htop](https://github.com/htop-dev/htop/).
- This application was written with many, _many_ libraries, and built on the
work of many talented people. This application would be impossible without their
work. I used to thank them all individually but the list got too large...
-- And of course, thanks to all contributors!
+- And of course, another round of thanks to all contributors and package maintainers!
diff --git a/assets/and_or_search.png b/assets/and_or_search.png
deleted file mode 100644
index e8b60490351faca2e218d93f7bdccfec75697a86..0000000000000000000000000000000000000000
GIT binary patch
literal 0
HcmV?d00001
literal 29601
zcmeFa2Ut_v)-D`us3@oiC{;y8ML