search

ratatui / ratatui-website

Ratatui Documentation
http://ratatui.rs/
MIT License
101 stars 77 forks source link

Add page for each widget #580

Open joshka opened 6 months ago

joshka commented 6 months ago

This is more of an idea issue for feedback from the other maintainers.

I think it might be nice to move the widget showcase over into /concepts/widgets and have a page per widget for any notes / details that don't end up being right for the API docs. I'd envisage this looking somewhat like:

EdJoPaTo commented 6 months ago

I would like to keep most of the stuff in the code. The website can link / reuse the example code but it shouldn't create another place to keep up to date when the examples change for whatever reason. That will be forgotten and ends up outdated sooner or later.

Especially code examples should be available in rustdoc to be automatically checked and adapted when the code changes.

Also, it's neat to clone the repo and have everything to look at locally. docs.rs / cargo doc --open is really neat. I would prefer that over a custom website unless there really is a reason for a custom website that significantly improves the developer experience. (which I dont see currently)

Only stuff that doesnt work in the code should be in a different place. wasm, screenshots / videos of them running would be the only thing that comes to mind which really benefits on a dedicated website. But as soon as the person is interested in creating it, they should end up in the docs.

joshka commented 6 months ago

I would like to keep most of the stuff in the code.

I share your concern on this one. We had a bunch of discussion before on discord and in issues when we first started creating the website, and I gave pretty much the same argument that you mentioned about splitting the effort, duplicating, etc. The primary argument against it that sways me to documenting things on the website is that the website has a much more rapid release cycle than the library (measured in minutes vs weeks).

The website is good for longer code samples than work well in API docs as well as tutorial style information. All (new) example code on the website should be sourced from actual source files that are checked in and run in CI, and there's a subtle difference that these run against the released version of Ratatui rather than the main branch. The website code component is a bit more powerful than the API docs code as it allows the code to be expanded for context.

WASM stuff will likely happen soon as there's a user that has a working version of this running well. https://gold-silver-copper.github.io/ https://github.com/gold-silver-copper/ratatui_egui_wasm. I could see it being eventually possible to do in browser editing of examples. That won't be available in the API docs.

unless there really is a reason for a custom website that significantly improves the developer experience

The dev experience is not just about seasoned rust devs, but also about guiding newer rustaceans. We often see (on discord, reddit, etc.) that devs are using Ratatui to build their first Rust app, so we look for ways to make the progression from website to API docs as easy as possible. Part of this is having good jumping off points from elsewhere in the website to get to the API docs. E.g. in the tutorials, when we mention a particular widget, it would be nice to link to https://ratatui.rs/concepts/widgets/block instead of the API docs directly.

TL;DR - this won't replace anything that should be in the API docs. It only augments it with things that don't belong or can't be in them as well as providing a gentle progression from website to docs.