Docs Should Use Stable API

[benwis]

trafficstars

I got some feedback from a new Leptos user that the use of nightly as the default in the docs screams that Leptos is still a lab experiment. I was thinking we could make the default stable and then have a toggle or tabbed code blocks for nightly. This would put our docs in line with our feature flagas well

[gbj]

Just so I understand properly: this is about the book, right? I think the regular docs default to stable syntax.

I'm okay with the proposal to have it tabbed, or even as something the user can set. I haven't done much work extending mdbook but I assume adding a bit of JavaScript to store a preference in localStorage and use it to pick the right tab would be easy enough.

If anyone has experience or interest in working on something like that, help would be great!

Editorializing, which doesn't affect the above

I have mixed feelings otherwise, for a couple reasons:

• It kind of *is* a lab experiment...
• I think the mental model that the nightly feature enables is **better** (accessing a reactive value is calling a function, no matter whether it's a signal, derived signal, or memo)
• I think people's concerns about nightly features and the nightly compiler are way overblown. In a couple years of using Rust pretty much every day, so far I've experienced one (1!) breaking change that required a change in Leptos but not user code, and (afaik?) zero compiler bugs that weren't fixed with a `cargo clean`

Obviously it's okay for people to disagree with me about any of that, and like I said I'm very open to a tabbed solution.

[benwis]

We can still be a lab experiment and still have a functional, working web framework crate! I think it's more about putting our best foot foard

[diversable]

As a stop-gap solution, perhaps we should just explicitly inform users how to switch to the Nightly toolchain (and back to stable!) using rustup, or using the toolchain file, so that they're not forced to look to other docs sources just to figure out how to use the Leptos crate - I think providing that info up front would provide a better 'startup' experience for users.

I know this info is just a google search away, but saving users a step - and teaching them something at the same time - can seriously reduce friction for new users..

[gbj]

As a stop-gap solution, perhaps we should just explicitly inform users how to switch to the Nightly toolchain (and back to stable!) using rustup

This is included in the Getting Started chapter of the book.

[diversable]

As a stop-gap solution, perhaps we should just explicitly inform users how to switch to the Nightly toolchain (and back to stable!) using rustup

This is included in the Getting Started chapter of the book.

Apologies - missed that when I was looking back at the book.

It might be helpful to include a statement (with link to the aforementioned page of the book) in the docs.rs page for Leptos that "nightly" is the preferred toolchain, though. I know it's redundant, but DRY is for code, not docs ;) Just a suggestion...

On a more helpful note: once I have a little better handle on Leptos, I'd like to help contribute to documentation - is there someone who's in charge of the docs right now that I should get some direction from for contributions?

[gbj]

It might be helpful to include a statement (with link to the aforementioned page of the book) in the docs.rs page for Leptos that "nightly" is the preferred toolchain, though. I know it's redundant, but DRY is for code, not docs ;) Just a suggestion...

There's a fairly prominent note in the README. Understood that people don't necessarily read the README, but it is the front page of the repo and the crates.io entry.

Adding the same thing, duplicated, to the doc comment in leptos/src/lib.rs so it appears on docs.rs is okay, I guess, but this does add extra maintenance burden/the possibility of discrepancies if the text of one is updated without updating the other.

And from the perspective of the docs.rs docs, for what it's worth, nightly is not the preferred syntax. Here is a very typical example. The stable syntax is used by default, with comments noting the alternate nightly syntax that's available. I think this is consistent across the docs, but I'm open to fixes if there are places where we use the nightly syntax on docs.rs as the default!

let (count, set_count) = create_signal(0);

// ✅ calling the getter clones and returns the value
//    this can be `count()` on nightly
assert_eq!(count.get(), 0);

// ✅ calling the setter sets the value
//    this can be `set_count(1)` on nightly
set_count.set(1);
assert_eq!(count.get(), 1);