docs: update README

This commit is contained in:
Alex Pasmantier 2025-06-28 17:29:15 +02:00 committed by alexandre pasmantier
parent c25a5bd75f
commit f52d4ef524
4 changed files with 57 additions and 123 deletions

View File

@ -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

View File

@ -8,7 +8,7 @@
![GitHub branch check runs](https://img.shields.io/github/check-runs/alexpasmantier/television/main)
![GitHub License](https://img.shields.io/github/license/alexpasmantier/television)
![tv on the curl codebase](https://github.com/user-attachments/assets/7d329ef3-4efe-4908-bbf8-e02744508eaf)
![tv running on the curl codebase](./assets/tv-curl.png)
</div>
@ -58,6 +58,9 @@ tv files
Switch channels using the remote control and pick from a large choice of [community-maintained channels](./cable):
![tv remote](./assets/tv-files-remote.png)
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

Binary file not shown.

After

Width:  |  Height:  |  Size: 496 KiB

View File

@ -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