Docs - landing page Layout section is out of place -> not newcomer friendly

[1oglop1]

Description

As a newcomer to Rust and Ratatui, I go to the documentation page https://docs.rs/ratatui/latest/ratatui/
The first few lines show perfect examples of what I can do with the library, then follow the minimal working example.
But then the Layout section contains some function ui() which explains how elements are composed,
however, the function example is completely disconnected from the previous code block, which makes it hard to grasp what is going on without diving deeper into the code.

Expected behavior

I'd expect the landing page to either provide a complete example or at least point me in the direction of examples.
Pointing to examples should not just be a text, but rather a link to a repo or page which explains more details about how to use
the library.

[joshka]

Thanks, this is some great feedback. Writing better docs is something that we're all working on. We'd appreciate any assitance you can spare to help wrangle some of this into order (whether that's via feedback or PRs).

If you haven't already found the following, these resources are available:

• The Readme: https://github.com/ratatui-org/ratatui#quickstart (has a more complete example)
• the Ratatui book: https://ratatui-org.github.io/ratatui-book/index.html
• the examples: https://github.com/ratatui-org/ratatui/tree/main/examples
• Several templates / samples:
  • https://github.com/ratatui-org/rust-tui-template (template)
  • https://ratatui-org.github.io/ratatui-async-template/ (book and template)
  • https://github.com/pmsanford/simple-tui-rs (example)

Ideally these should be better cross linked in all the right places so concretely we need to:

• Compare the README and docs.rs main page and ensure that they are either consistent or link to each other appropriately (we could either make these exactly the same, or simplify one and point to the other, but we need to understand which bits are useful in each first). cargo-rdme is possibly something to consider here
• Ensure that mentions of "examples" actually link to the examples
• Ensure that we link to the Book more
• Highlight the available templates
• Ensure that the various docs page links all to the other docs (no dead ends)
• Document the examples more (this is a larger task)

Happy to hear more suggestions on this / take PRs if you're interested in helping out.

[1oglop1]

Thanks! I will look into it.

I'd like to contribute back when I get a hang of the project. Because the examples look pretty good. It's just a pity they are a bit hidden. 
I am not a fan of a separate rust book because it is one more place to look at and maintain the parity. 

I hope that the suggested solution here will soon become a reality Because it's pretty much standard in other languages (e.g. python->Sphinx)
 https://internals.rust-lang.org/t/rustdoc-include-an-external-markdown-file-as-a-separate-page/15994

[joshka]

I'd like to contribute back when I get a hang of the project. Because the examples look pretty good. It's just a pity they are a bit hidden.

If you like the look of the current examples, check out PR #500 for some inspiration.

Rendered versions of the examples (in the examples Readme) have only been since the end of July PR #303 - before that you had to run the examples yourself to see what they looked like. I actually want this to go a few steps further and use the rendered examples directly in the docs.

I am not a fan of a separate rust book because it is one more place to look at and maintain the parity.

One of the major things that dictates a separate repo rather than just the docs.rs api docs for us is that the speed of iteration on docs is 1-2 of magnitude faster than of the library. (78 PRs merged since June when the book started compared with just 3 releases of ratatui in the last 4 months). We won't be moving away from having a book, but we'll definitely try to keep the right sort of linkage between them.

I hope that the suggested solution here will soon become a reality Because it's pretty much standard in other languages (e.g. python->Sphinx)

That does sound neat for some things. Clap is an example that the docs.rs approach leads to something

I hope that the suggested solution here will soon become a reality Because it's pretty much standard in other languages (e.g. python->Sphinx)

Sounds interesting.

[kdheepak]

I kind of agree that this page https://docs.rs/ratatui/latest/ratatui/ is not a good landing page for a new user.

Everything between Getting Started and Features, i.e.:

ratatui/src/lib.rs

Lines 8 to 163 in dd9a8df

	//! # Get started
	//!
	//! ## Adding `ratatui` as a dependency
	//!
	//! Add the following to your `Cargo.toml`:
	//! ```toml
	//! [dependencies]
	//! crossterm = "0.27"
	//! ratatui = "0.23"
	//! ```
	//!
	//! The crate is using the `crossterm` backend by default that works on most platforms. But if for
	//! example you want to use the `termion` backend instead. This can be done by changing your
	//! dependencies specification to the following:
	//!
	//! ```toml
	//! [dependencies]
	//! termion = "2.0.1"
	//! ratatui = { version = "0.23", default-features = false, features = ['termion'] }
	//! ```
	//!
	//! The same logic applies for all other available backends.
	//!
	//! ## Creating a `Terminal`
	//!
	//! Every application using `ratatui` should start by instantiating a `Terminal`. It is a light
	//! abstraction over available backends that provides basic functionalities such as clearing the
	//! screen, hiding the cursor, etc.
	//!
	//! ```rust,no_run
	//! use std::io;
	//! use ratatui::prelude::*;
	//!
	//! fn main() -> Result<(), io::Error> {
	//! let stdout = io::stdout();
	//! let backend = CrosstermBackend::new(stdout);
	//! let mut terminal = Terminal::new(backend)?;
	//! Ok(())
	//! }
	//! ```
	//!
	//! If you had previously chosen `termion` as a backend, the terminal can be created in a similar
	//! way:
	//!
	//! ```rust,ignore
	//! use std::io;
	//! use ratatui::prelude::*;
	//! use termion::raw::IntoRawMode;
	//!
	//! fn main() -> Result<(), io::Error> {
	//! let stdout = io::stdout().into_raw_mode()?;
	//! let backend = TermionBackend::new(stdout);
	//! let mut terminal = Terminal::new(backend)?;
	//! Ok(())
	//! }
	//! ```
	//!
	//! You may also refer to the examples to find out how to create a `Terminal` for each available
	//! backend.
	//!
	//! ## Building a User Interface (UI)
	//!
	//! Every component of your interface will be implementing the `Widget` trait. The library comes
	//! with a predefined set of widgets that should meet most of your use cases. You are also free to
	//! implement your own.
	//!
	//! Each widget follows a builder pattern API providing a default configuration along with methods
	//! to customize them. The widget is then rendered using [`Frame::render_widget`] which takes your
	//! widget instance and an area to draw to.
	//!
	//! The following example renders a block of the size of the terminal:
	//!
	//! ```rust,no_run
	//! use std::{io, thread, time::Duration};
	//! use ratatui::{prelude::*, widgets::*};
	//! use crossterm::{
	//! event::{self, DisableMouseCapture, EnableMouseCapture},
	//! execute,
	//! terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
	//! };
	//!
	//! fn main() -> Result<(), io::Error> {
	//! // setup terminal
	//! enable_raw_mode()?;
	//! let mut stdout = io::stdout();
	//! execute!(stdout, EnterAlternateScreen, EnableMouseCapture)?;
	//! let backend = CrosstermBackend::new(stdout);
	//! let mut terminal = Terminal::new(backend)?;
	//!
	//! terminal.draw(|f| {
	//! let size = f.size();
	//! let block = Block::default()
	//! .title("Block")
	//! .borders(Borders::ALL);
	//! f.render_widget(block, size);
	//! })?;
	//!
	//! // Start a thread to discard any input events. Without handling events, the
	//! // stdin buffer will fill up, and be read into the shell when the program exits.
	//! thread::spawn(|| loop {
	//! event::read();
	//! });
	//!
	//! thread::sleep(Duration::from_millis(5000));
	//!
	//! // restore terminal
	//! disable_raw_mode()?;
	//! execute!(
	//! terminal.backend_mut(),
	//! LeaveAlternateScreen,
	//! DisableMouseCapture
	//! )?;
	//! terminal.show_cursor()?;
	//!
	//! Ok(())
	//! }
	//! ```
	//!
	//! ## Layout
	//!
	//! The library comes with a basic yet useful layout management object called `Layout`. As you may
	//! see below and in the examples, the library makes heavy use of the builder pattern to provide
	//! full customization. And `Layout` is no exception:
	//!
	//! ```rust,no_run
	//! use ratatui::{prelude::*, widgets::*};
	//!
	//! fn ui<B: Backend>(f: &mut Frame<B>) {
	//! let chunks = Layout::default()
	//! .direction(Direction::Vertical)
	//! .margin(1)
	//! .constraints(
	//! [
	//! Constraint::Percentage(10),
	//! Constraint::Percentage(80),
	//! Constraint::Percentage(10)
	//! ].as_ref()
	//! )
	//! .split(f.size());
	//! let block = Block::default()
	//! .title("Block")
	//! .borders(Borders::ALL);
	//! f.render_widget(block, chunks[0]);
	//! let block = Block::default()
	//! .title("Block 2")
	//! .borders(Borders::ALL);
	//! f.render_widget(block, chunks[1]);
	//! }
	//! ```
	//!
	//! This let you describe responsive terminal UI by nesting layouts. You should note that by default
	//! the computed layout tries to fill the available space completely. So if for any reason you might
	//! need a blank space somewhere, try to pass an additional constraint and don't use the
	//! corresponding area.
	//!
	//! # Features

could be replaced with two links:

• https://ratatui-org.github.io/ratatui-book/installation.html
• https://ratatui-org.github.io/ratatui-book/tutorial/hello-world/index.html

And it would be a much better onboarding experience for users of any level of experience (imo).

[kdheepak]

For reference, clap's landing page:

has links to start off with + one code example with no explanations (which I like) further down the page.

It gives people as idea of what kind of syntax is required to use this package just to recognize patterns without any deeper prose or explanations (for example, we talk about crossterm and termion and terminal backends in the first few lines; the example has a thread spawn with event read which probably no one will use in real code; there's a line at the end about computed layouts and blank spaces; etc which is all not required for users or potential users that are just landing on the page for the first time).

Serde goes one step further: no code examples on the landing page + a single line that tells users to do to https://serde.rs for additional examples (which happens to be a mdbook generated website):

I really like that approach.

[joshka]

Some subjective observations:

• People tend to link to one of {crate page, docs page, github repo} when linking a lbrary, so ideally they should have the same information on them to avoid communicating different things on each page.
• I tend to use the information on those pages as a metric for whether to invest further in learning a particular crate, so the initial information should be compelling enough to dig deeper. When I view a crate page for something TUI related, I want to see the following:
  • What it looks like
  • What it does (a list of all high level features)
  • A basic code example (not a tutorial walk through, but only enough to help me know which main types I need to know about) - this led to the code example in https://github.com/ratatui-org/ratatui#quickstart
  • MSRV
  • Links to related crates

The docs / readme don't need Cargo.toml examples or info on alternate backend config. That belongs elsewhere.
It would be nice to have a small image of each widget (~20x3 cell) to show what each can do, I think it's good to have these on the main landing pages instead of at a secondary link, but these could also go on the widgets module page if we think there's too much info.

[a-kenji]

Please also keep the text editor side in mind. The main way I interact with the documentation is through an lsp popup window.
That makes is also very trivial to copy parts of examples that are surfaced in doc comments and adjust them amongst other things.

[joshka]

Please also keep the text editor side in mind. The main way I interact with the documentation is through an lsp popup window.
That makes is also very trivial to copy parts of examples that are surfaced in doc comments and adjust them amongst other things.

Good call out - can you screenshot some examples? It would be helpful to have an example of how the docs render right now via the LSP.

[kdheepak]

For me in neovim:

[joshka]

Neat. Thanks :)