diff --git a/README.md b/README.md index e8655979..b111350e 100644 --- a/README.md +++ b/README.md @@ -73,8 +73,8 @@ As (yet another) process/system visualization and management application, bottom - [A process widget](https://clementtsang.github.io/bottom/nightly/usage/widgets/process/) for displaying, sorting, and searching info about processes, as well as support for: - - Kill signals - - Tree mode + - [Kill signals](https://clementtsang.github.io/bottom/nightly/usage/widgets/process/#process-termination) + - [Tree mode](https://clementtsang.github.io/bottom/nightly/usage/widgets/process/#tree-mode) - Cross-platform support for Linux, macOS, and Windows, with more planned in the future. diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 00000000..33d89d17 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,47 @@ +# Extended Documentation + +This is where the extended documentation resides, hosted on GitHub Pages. We use [MkDocs](https://www.mkdocs.org/), +[Material for MkDocs](https://squidfunk.github.io/mkdocs-material/), and [mike](https://github.com/jimporter/mike). + +## Running locally + +```bash +# Change directories to the documentation. +cd docs/ + +# Create and activate venv. +python -m venv venv +source venv/bin/activate + +# Install requirements +pip install -r requirements.txt + +# Run mkdocs +venv/bin/mkdocs serve +``` + +## Deploying + +Deploying is done via [mike](https://github.com/jimporter/mike). + +### Nightly + +```bash +cd docs +mike deploy nightly --push +``` + +### Stable + +```bash +cd docs + +# Rename the previous stable version +mike retitle --push stable $OLD_STABLE_VERSION + +# Set the newest version as the most recent stable version +mike deploy --push --update-aliases $RELEASE_VERSION stable + +# Append a "(stable)" string to the end. +mike retitle --push $RELEASE_VERSION "$RELEASE_VERSION (stable)" +``` diff --git a/docs/content/assets/screenshots/process/process_kill_linux.webp b/docs/content/assets/screenshots/process/process_kill_linux.webp new file mode 100644 index 00000000..26fbb78e Binary files /dev/null and b/docs/content/assets/screenshots/process/process_kill_linux.webp differ diff --git a/docs/content/assets/screenshots/process/process_kill_simple.webp b/docs/content/assets/screenshots/process/process_kill_simple.webp new file mode 100644 index 00000000..c349c2ae Binary files /dev/null and b/docs/content/assets/screenshots/process/process_kill_simple.webp differ diff --git a/docs/content/contribution/documentation.md b/docs/content/contribution/documentation.md index b39ca709..5a1a6ad6 100644 --- a/docs/content/contribution/documentation.md +++ b/docs/content/contribution/documentation.md @@ -2,43 +2,49 @@ ## When should documentation changes be done? -- Whenever a new feature is added, a bug is fixed, or a breaking change is made, it should be documented where appropriate (ex: `README.md`, changelog, etc.) +- Whenever a new feature is added, a bug is fixed, or a breaking change is made, it should be documented where + appropriate (ex: `README.md`, changelog, etc.) - New methods of installation are always appreciated and should be documented ## What pages need documentation? There are a few areas where documentation changes are often needed: -- The [extended documentation](https://clementtsang.github.io/bottom/nightly/) (AKA here) - The [`README.md`](https://github.com/ClementTsang/bottom/blob/master/README.md) - The help menu inside of the application (located [here](https://github.com/ClementTsang/bottom/blob/master/src/constants.rs)) +- The [extended documentation](https://clementtsang.github.io/bottom/nightly/) (here) - The [`CHANGELOG.md`](https://github.com/ClementTsang/bottom/blob/master/CHANGELOG.md) -## How should I add documentation? +## How should I add/update documentation? -1. Fork the repository first and make changes there. +1. Fork the repository to make changes in. 2. Where you're adding documentation will probably affect what you need to do: - ### `README.md` or `CHANGELOG.md` +

README.md or CHANGELOG.md

For changes to [`README.md`](https://github.com/ClementTsang/bottom/blob/master/README.md) and [`CHANGELOG.md`](https://github.com/ClementTsang/bottom/blob/master/CHANGELOG.md), just follow the formatting provided and use any editor. - ### Help menu + Generally, changes to [`CHANGELOG.md`](https://github.com/ClementTsang/bottom/blob/master/CHANGELOG.md) will be handled + by a maintainer, and changes should follow the [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) format, as + well as link to the relevant PR or issue. + +

Help menu

For changes to the help menu, try to refer to the existing code within `src/constants.rs` on how the help menu is generated. - ### Extended documentation +

Extended documentation

For changes to the extended documentation, you'll probably want [MkDocs](https://www.mkdocs.org/), [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/), `mdx_truly_sane_lists`, and optionally [Mike](https://github.com/jimporter/mike) installed to provide live reloading and preview for your changes. They aren't needed but it'll help with validating your changes. - You can do so through `pip` or your system's package managers. If you use `pip`, you probably would want to do something like so through a venv: + You can do so through `pip` or your system's package managers. If you use `pip`, you can use venv to install the + documentation dependencies: ```bash - # Starting from the repo root: + # Change directories to the documentation. cd docs/ - # Create venv and activate + # Create and activate venv. python -m venv venv source venv/bin/activate @@ -49,4 +55,7 @@ There are a few areas where documentation changes are often needed: venv/bin/mkdocs serve ``` -3. Once you have your documentation changes done, submit it as a pull request. For more information regarding that, refer to [Issues, Pull Requests, and Discussions](../issues-and-pull-requests/). + This will serve a local version of the docs that you can open on your browser. It will update as you make changes. + +3. Once you have your documentation changes done, submit it as a pull request. For more information regarding that, + refer to [Issues, Pull Requests, and Discussions](../issues-and-pull-requests/). diff --git a/docs/content/troubleshooting.md b/docs/content/troubleshooting.md index 3015c969..c9fd5852 100644 --- a/docs/content/troubleshooting.md +++ b/docs/content/troubleshooting.md @@ -8,7 +8,7 @@ render braille fonts.
Example of a terminal with no braille font. -
Powershell shown missing braille fonts
+
An example of missing braille fonts in Powershell
One alternative is to use the `--dot_marker` option to render graph charts using dots instead of the braille characters, @@ -16,7 +16,7 @@ which generally seems better supported out of the box, at the expense of looking
Example of running bottom with the dot marker flag -
Example using btm --dot_marker
+
Example using btm --dot_marker
Another (better) alternative is to install a font that supports braille fonts, and configure your terminal to use it. For example, installing @@ -41,16 +41,16 @@ Let's say you're installing [Iosevka](https://github.com/be5invis/Iosevka). The
Regedit menu showing how to add a new font for Command Prompt/PowerShell -
The last entry is the new entry for Iosevka
+
The last entry is the new entry for Iosevka
-5. Then, open the Command Prompt/PowerShell, and right click on the top bar, and open `Properties`: +1. Then, open the Command Prompt/PowerShell, and right click on the top bar, and open "Properties":
Opening the properties menu in Command Prompt/PowerShell
-6. From here, go to `Font`, and set the font to your new font (e.g. `Iosevka`): +1. From here, go to "Font", and set the font to your new font (so in this example, Iosevka):
Setting a new font in Command Prompt/PowerShell diff --git a/docs/content/usage/widgets/process.md b/docs/content/usage/widgets/process.md index 3285a7a3..5b157019 100644 --- a/docs/content/usage/widgets/process.md +++ b/docs/content/usage/widgets/process.md @@ -50,6 +50,24 @@ is added together when displayed. Note that the process state and user columns are disabled in this mode. +### Process termination + +Pressing ++d+d++ or ++f9++ will allow you to terminate the currently selected process/process group. On Unix-like +operating systems, you are also able to control which specific signals to send (e.g. `SIGKILL`, `SIGTERM`). + +
+ A picture of the process kill menu on Linux. +
The process termination menu on Linux
+
+ +If you're on Windows, or if the `disable_advanced_kill` flag is set in the options or command-line, then a simpler termination +screen will be shown to confirm whether you want to kill that process/process group. + +
+ A picture of the process kill menu on Windows. +
The process termination menu on Windows
+
+ ### Tree mode Pressing ++t++ or ++f5++ in the table toggles tree mode in the process widget, displaying processes in regards to their parent-child process relationships.