docs: Add new structure for README
This commit is contained in:
Timo Reymann
Binary file not shown.
|
After Width: | Height: | Size: 20 KiB |
@@ -1,54 +1,82 @@
|
||||
bash-tui-toolkit
|
||||
===
|
||||
[](https://pre-commit.com/)
|
||||
[](https://dl.circleci.com/status-badge/redirect/gh/timo-reymann/bash-tui-toolkit/tree/main)
|
||||
[](https://github.com/timo-reymann/bash-tui-toolkit/blob/main/LICENSE)
|
||||
[](https://app.circleci.com/pipelines/github/timo-reymann/bash-tui-toolkit)
|
||||
[](https://github.com/timo-reymann/bash-tui-toolkit/releases)
|
||||
[](https://renovatebot.com)
|
||||
[](https://pre-commit.com/)
|
||||
|
||||
Toolkit to create simple Terminal UIs using plain bash builtins
|
||||
<p align="center">
|
||||
<img width="300" src="./.github/images/logo.png">
|
||||
<br />
|
||||
Toolkit to create interactive and shiny terminal UIs using plain bash builtins
|
||||
</p>
|
||||
|
||||
## Goals
|
||||
## Features
|
||||
|
||||
- clean and standardized API
|
||||
- provide a simple and clear default set of elements to use creating an interactive terminal UI
|
||||
- be clean and minimalistic
|
||||
- clean and minimalistic design
|
||||
- zero dependencies to be installed
|
||||
- parts can be used separately
|
||||
- parts can be used modular
|
||||
|
||||
## Install
|
||||
1. Download the bundle (entire lib) or single compoennt from [releases](https://github.com/timo-reymann/bash-tui-toolkit/releases)
|
||||
## Requirements
|
||||
|
||||
- [bash 3+](https://www.gnu.org/software/bash/)
|
||||
|
||||
## Installation
|
||||
|
||||
1. Download the bundle (entire lib) or single compoennt
|
||||
from [releases](https://github.com/timo-reymann/bash-tui-toolkit/releases)
|
||||
2. Source the bundle in your script or embed
|
||||
|
||||
## Documentation
|
||||
## Usage
|
||||
|
||||
For a list of available modules and their documentation please check the [docs/modules](./docs/modules) folder
|
||||
|
||||
## Tested with
|
||||
For a complete playground demo check [test.sh](./test.sh).
|
||||
|
||||
> Since there are some weird combinations/side effects based on the platform you might use there are different side effects that might occur
|
||||
>
|
||||
> If you use it on a different platform successfully please create a PR to add a item here :)
|
||||
## Motivation
|
||||
|
||||
| OS | Version of OS | Terminal emulator | Bash Major Version | Works
|
||||
| :------ | :------------ | :---------------- | :----------------- | :-----
|
||||
| Ubuntu | 20 | Tilix | 4 | ✔️
|
||||
| Ubuntu | 20 | xterm | 4 | ✔️
|
||||
| Ubuntu | 22 | Tilix | 5 | ✔️
|
||||
| Alpine | 3 | n/a | 5 | ✔️
|
||||
| MacOS | Monterey | iTerm | 3 | ✔️
|
||||
| MacOS | Monterey | iTerm2 | 3 | ✔️
|
||||
| Windows | 10 | Windows Terminal | 4 | ✔️
|
||||
| Windows | 10 | Git Bash | 4 | ✔️
|
||||
| Windows | 10 | Hyper | 4 | ✔️
|
||||
Providing a clean bash UI sometimes becomes a mess and interactivity is hard to achieve especially when it should be
|
||||
portable.
|
||||
|
||||
<!--
|
||||
if you encounter a platform where there are problems feel free to add works with ❌
|
||||
-->
|
||||
The target is to provide a simple-to-use toolkit that can be dropped into any bash script and is compatible no matter
|
||||
the target system.
|
||||
|
||||
## Documentation
|
||||
|
||||
- [Modules](./docs/modules) - Modules available and their usage
|
||||
- [Compability table](./docs/Compability.md) - Known combinations of OS/Bash Version/Terminal emulators that work guaranteed
|
||||
|
||||
## Contributing
|
||||
|
||||
I love your input! I want to make contributing to this project as easy and transparent as possible, whether it's:
|
||||
|
||||
- Reporting a bug
|
||||
- Discussing the current state of the configuration
|
||||
- Submitting a fix
|
||||
- Proposing new features
|
||||
- Becoming a maintainer
|
||||
|
||||
To get started please read the [Contribution Guidelines](./CONTRIBUTING.md).
|
||||
|
||||
## Development
|
||||
|
||||
### Requirements
|
||||
- bash 3+
|
||||
- docker 19+
|
||||
- GNU make
|
||||
|
||||
## Generate documentation
|
||||
- [GNU make](https://www.gnu.org/software/make/)
|
||||
- [Docker](https://docs.docker.com/get-docker/)
|
||||
- [pre-commit](https://pre-commit.com/)
|
||||
|
||||
### Build
|
||||
|
||||
```
|
||||
make build
|
||||
```
|
||||
|
||||
### Update documentation
|
||||
|
||||
To update the module documentation you just need to run
|
||||
|
||||
```sh
|
||||
@@ -58,16 +86,13 @@ make generate-docs
|
||||
This builds the documentation inside a docker container and updates the
|
||||
repo locally. Afterwards just commit the docs with your code changes
|
||||
|
||||
## Build
|
||||
To combine the script(s) you just need to run
|
||||
|
||||
```sh
|
||||
make build
|
||||
```
|
||||
## Credits
|
||||
|
||||
The combined artifacts can be found in `dist/`
|
||||
- Logo
|
||||
- Bash logo from [pngegg](https://www.pngegg.com/en/png-pxpgu)
|
||||
- Toolbox logo from [IconExperience.com](https://www.iconexperience.com/g_collection/icons/?icon=toolbox)
|
||||
|
||||
## Alternatives
|
||||
- [kahkhang/Inquirer.sh](https://github.com/kahkhang/Inquirer.sh) - List, Checkbox and Text Input with more advanced
|
||||
validation
|
||||
|
||||
|
||||
@@ -0,0 +1,23 @@
|
||||
Compability
|
||||
===
|
||||
|
||||
The toolkit is known to work with the following platforms listed below.
|
||||
|
||||
If you feel like an important one is missing feel free to create an issue or PR directly for the file.
|
||||
|
||||
> Since there are some weird combinations/side effects based on the platform you might use there are different side
|
||||
> effects that might occur
|
||||
>
|
||||
> If you use it on a different platform successfully please create a PR to add a item here :)
|
||||
|
||||
| OS | Version of OS | Terminal emulator | Bash Major Version | Works
|
||||
|:--------|:--------------|:------------------|:-------------------|:------
|
||||
| Ubuntu | 20 | Tilix | 4 | ✔️
|
||||
| Ubuntu | 20 | xterm | 4 | ✔️
|
||||
| Ubuntu | 22 | Tilix | 5 | ✔️
|
||||
| Alpine | 3 | n/a | 5 | ✔️
|
||||
| MacOS | Monterey | iTerm | 3 | ✔️
|
||||
| MacOS | Monterey | iTerm2 | 3 | ✔️
|
||||
| Windows | 10 | Windows Terminal | 4 | ✔️
|
||||
| Windows | 10 | Git Bash | 4 | ✔️
|
||||
| Windows | 10 | Hyper | 4 | ✔️
|
||||
Reference in New Issue
Block a user