mirror of
https://github.com/alexpasmantier/television.git
synced 2025-07-29 06:11:37 +00:00
docs: update README
This commit is contained in:
parent
c25a5bd75f
commit
f52d4ef524
139
CONTRIBUTING.md
139
CONTRIBUTING.md
@ -1,30 +1,16 @@
|
||||
# Contributing
|
||||
|
||||
First of all, thanks for considering contributing to this project. All contributions are welcome, whether they are bug
|
||||
reports, documentation improvements, feature requests, or pull requests.
|
||||
First of all, thanks for considering contributing to this project. All contributions are welcome, whether they are bug reports, documentation improvements, feature requests, or pull requests.
|
||||
|
||||
Please make sure to read and follow our [Code of Conduct](CODE_OF_CONDUCT.md) to ensure a positive experience for
|
||||
everyone involved.
|
||||
Please make sure to read and follow our [Code of Conduct](CODE_OF_CONDUCT.md) to ensure a positive experience for everyone involved.
|
||||
|
||||
If you're not sure where to start, take a look at the [Hot Topics](#hot-topics) section for some ideas on what you could
|
||||
work on.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [Getting started](#getting-started)
|
||||
- [Prerequisites](#prerequisites)
|
||||
- [Forking the repository and setting up the project](#forking-the-repository-and-setting-up-the-project)
|
||||
- [Building the project](#building-the-project)
|
||||
- [Project structure](#project-structure)
|
||||
- [Contributing a new channel](#contributing-a-new-channel)
|
||||
- [Hot Topics](#hot-topics)
|
||||
If you're not sure where to start, take a look at the [Hot Topics](#hot-topics) section for some ideas on what you could work on.
|
||||
|
||||
## Getting started
|
||||
|
||||
### Prerequisites
|
||||
|
||||
These are pretty much the only things you need to have installed on your machine to get started with contributing to
|
||||
this project:
|
||||
These are pretty much the only things you need to have installed on your machine to get started with contributing to this project:
|
||||
|
||||
- the [Rust](https://www.rust-lang.org/tools/install) toolchain installed on your machine
|
||||
- any working version of [Git](https://git-scm.com/downloads)
|
||||
@ -32,8 +18,7 @@ this project:
|
||||
|
||||
### Forking the repository and setting up the project
|
||||
|
||||
1. Click on the `Fork` button at the top right corner of the repository page to create a copy of the repository to your
|
||||
GitHub account.
|
||||
1. Click on the `Fork` button at the top right corner of the repository page to create a copy of the repository to your GitHub account.
|
||||
2. Clone the forked repository to your local machine by running the following command in your terminal:
|
||||
```shell
|
||||
git clone https://github.com/<your-username>/television.git
|
||||
@ -51,8 +36,7 @@ this project:
|
||||
```shell
|
||||
git checkout -b <branch-name>
|
||||
```
|
||||
6. Make your changes and test them locally. Predefined commands are available to make your life simpler, using them
|
||||
spares some time and effort:
|
||||
6. Make your changes and test them locally. Predefined commands are available to make your life simpler, using them spares some time and effort:
|
||||
```shell
|
||||
just --list
|
||||
```
|
||||
@ -65,8 +49,7 @@ this project:
|
||||
```shell
|
||||
git push origin <branch-name>
|
||||
```
|
||||
8. If not done automatically, create a pull request by navigating to the original repository and clicking on the
|
||||
`New pull request` button.
|
||||
8. If not done automatically, create a pull request by navigating to the original repository and clicking on the `New pull request` button.
|
||||
|
||||
### Developing locally
|
||||
|
||||
@ -84,8 +67,8 @@ just run
|
||||
|
||||
**Accessing the Logs:**
|
||||
|
||||
The logs are written to a file called `television.log` in a directory that depends on your operating system /
|
||||
configuration:
|
||||
The logs are written to a file called `television.log` in a directory that depends on your operating system / configuration:
|
||||
|
||||
| Platform | Location |
|
||||
|----------|----------|
|
||||
| Linux | `$XDG_DATA_HOME/television/television.log` or `$HOME/.local/share/television/television.log` |
|
||||
@ -112,108 +95,20 @@ Running the tests can be done with:
|
||||
just test
|
||||
```
|
||||
|
||||
### Project structure
|
||||
|
||||
The project is laid out in several rust crates that are organized in the following way:
|
||||
|
||||
- `television`: the main binary crate that contains the CLI application
|
||||
- `television_derive`: a library crate that contains the derive macros used in the project
|
||||
|
||||
### Contributing a new channel
|
||||
|
||||
`television` is built around the concept of _channels_.
|
||||
|
||||
From a technical standpoint, channels are structs that implement the `OnAir` trait defined in
|
||||
`television/channels/mod.rs`.
|
||||
|
||||
They can be anything that can respond to a user query and return a result under the form of a list of entries. This
|
||||
means channels can be anything from conventional data sources you might want to search through (like files, git
|
||||
repositories, remote filesystems, environment variables etc.) to more exotic implementations that might include a REPL,
|
||||
a calculator, a web browser, search through your spotify library, your email, etc.
|
||||
|
||||
As mentioned in [Project structure](#project-structure) `television`
|
||||
uses [crates](https://doc.rust-lang.org/book/ch07-01-packages-and-crates.html) for its different subcomponents (
|
||||
_previewers_, _channels_, _utils_, etc).
|
||||
|
||||
When contributing a new channel, you should create a new module in the `crate::channels` crate with a new struct for
|
||||
your channel and ensure that it implements the `OnAir` trait defined
|
||||
in [crates/television-channels/src/channels.rs](crates/television-channels/src/channels.rs)
|
||||
|
||||
```rust
|
||||
// crates/television-channels/src/channels/my_new_channel.rs
|
||||
|
||||
use crate::channels::OnAir;
|
||||
|
||||
pub struct MyNewChannel;
|
||||
|
||||
impl OnAir for MyNewChannel {
|
||||
// Implement the OnAir trait for your channel here
|
||||
}
|
||||
```
|
||||
|
||||
You should also add your channel to the `TelevisionChannel` enum in the `crate::channels` crate.
|
||||
|
||||
```rust
|
||||
// crates/television-channels/src/mod
|
||||
|
||||
#[derive(ToUnitChannel, ToCliChannel, Broadcast)]
|
||||
pub enum TelevisionChannel {
|
||||
// Other channels
|
||||
MyNewChannel,
|
||||
}
|
||||
```
|
||||
|
||||
☝️ There are built-in channels in `television` that you might want to draw inspiration from if need be, they're located
|
||||
at [crates/television-channels/src/channels](crates/television-channels/src/channels).
|
||||
|
||||
**TODO**: document transitions between channels and previewers
|
||||
Contributing a new channel is pretty straightforward.
|
||||
1. create a new branch, add and commit your new channel's TOML file under `cable/unix` (or `cable/windows` depending on your usecase)
|
||||
2. push your commit and create a PR
|
||||
|
||||
## Hot Topics
|
||||
|
||||
### Current hot topics:
|
||||
|
||||
- shell integration (autocomplete, keybindings)
|
||||
- packaging for various linux package managers (apt, dnf, ...)
|
||||
- configuring custom actions for each channel
|
||||
|
||||
### Other ideas:
|
||||
|
||||
See the [todo list](./TODO.md) for ideas.
|
||||
|
||||
- `Customization`:
|
||||
- allow users to further customize the behavior of the application (e.g. the default channel, fuzzy matching
|
||||
constants, channel heuristics, etc.)
|
||||
- `Channels`:
|
||||
- new channel ideas (builtin or cable):
|
||||
- shell history
|
||||
- directories
|
||||
- git (commits, branches, status, diff, ...)
|
||||
- remote filesystems (s3, ...)
|
||||
- kubernetes resources (jobs, pods, deployments, services, ...)
|
||||
- recent directories
|
||||
- makefile commands
|
||||
- etc.
|
||||
- add more tests for existing channels
|
||||
- `Previewers`:
|
||||
- new previewer ideas:
|
||||
- previewing text in documents (pdfs, archives, ...)
|
||||
- previewing images (actually already implemented but commented out)
|
||||
- remote files (s3, ...)
|
||||
- etc.
|
||||
- more tests for existing previewers
|
||||
- `Documentation`:
|
||||
- add more technical documentation to the project
|
||||
- general design of the TUI application
|
||||
- design of channels, previewers, transitions, etc.
|
||||
- how to contribute a new channel, previewer, etc.
|
||||
- more docstrings
|
||||
- `Performance/Refactoring`:
|
||||
- working on reducing coupling between the different crates in the project
|
||||
- working on reducing the number of allocations and copies in the code
|
||||
- writing benchmarks for different parts of the application
|
||||
- `Project`:
|
||||
- polish project configuration:
|
||||
- CI/CD
|
||||
- packaging for various linux package managers (dnf, ...)
|
||||
- sorting options
|
||||
- ansi parsing
|
||||
- contributing new channels
|
||||
- improving code documentation
|
||||
|
||||
|
||||
|
||||
|
@ -8,7 +8,7 @@
|
||||

|
||||

|
||||
|
||||

|
||||

|
||||
|
||||
</div>
|
||||
|
||||
@ -58,6 +58,9 @@ tv files
|
||||
Switch channels using the remote control and pick from a large choice of [community-maintained channels](./cable):
|
||||
|
||||

|
||||
|
||||
See the [channels docs](https://github.com/alexpasmantier/television/blob/main/docs/channels.md) for more info on how to set these up.
|
||||
|
||||
## Usage
|
||||
```bash
|
||||
tv # default channel
|
||||
|
BIN
assets/tv-curl.png
Normal file
BIN
assets/tv-curl.png
Normal file
Binary file not shown.
After Width: | Height: | Size: 496 KiB |
@ -88,6 +88,42 @@ tv my-awesome-channel
|
||||
|
||||
The complete channel format spec can be found below.
|
||||
|
||||
## Templating syntax
|
||||
Several channel fields can be formatted dynamically using the syntax described in the [string-pipeline](https://docs.rs/string_pipeline/0.12.0/string_pipeline/) crate.
|
||||
|
||||
Here's a quick TLDR if you're feeling lazy:
|
||||
|
||||
**Basic transformations:**
|
||||
|
||||
```bash
|
||||
# Extract middle items: "a,b,c,d,e"
|
||||
"{split:,:1..3}"
|
||||
# Output: "b,c"
|
||||
|
||||
# Clean and format names: " john , jane , bob "
|
||||
'{split:,:..|map:{trim|upper|append:!}}'
|
||||
# Output: "JOHN!,JANE!,BOB!"
|
||||
|
||||
# Extract numbers and pad with zeros: "item1,thing22,stuff333"
|
||||
'{split:,:..|map:{regex_extract:\d+|pad:3:0:left}}'
|
||||
# Output: "001,022,333"
|
||||
```
|
||||
|
||||
**More niche use-cases:**
|
||||
|
||||
```bash
|
||||
# Filter files, format as list: "app.py,readme.md,test.py,data.json"
|
||||
'{split:,:..|filter:\.py$|sort|map:{prepend:• }|join:\n}'
|
||||
# Output: "• app.py\n• test.py"
|
||||
|
||||
# Extract domains from URLs: "https://github.com,https://google.com"
|
||||
'{split:,:..|map:{regex_extract://([^/]+):1|upper}}'
|
||||
# Output: "GITHUB.COM,GOOGLE.COM"
|
||||
|
||||
# Debug complex processing: "apple Banana cherry Date"
|
||||
"{split: :..|filter:^[A-Z]|sort:desc}"
|
||||
# Output: Date,Banana
|
||||
```
|
||||
## Channel specification
|
||||
#### high-level sections
|
||||
|
||||
|
Loading…
x
Reference in New Issue
Block a user