refactor(lang/rust): rust language guide

[vados-cosmonic]

This commit heavily refactors the rust language guide, accomplishing a few goals:

• Moving from cargo component to native rust toolchain
• Removing sections with advanced funtionality

We're probably going to have to heavily discuss this, but I'm putting this PR up so we have something concrete do discuss.

We likely need:

1. New section(s) for the "calculator" phase/step 2 of the guide
2. New structure for the "advanced" pieces

With regards to (1), the initial language guide seems really well served by the basic component + run example. It's easy to understand, and a quick win for the average new reader. Adding in imports and composition into the calculator component really feels like a step 2/more advanced guide that we should separate out and let people navigate to.

With regards to (2), many of the advanced sections at the bottom (type mappings, etc) really also feel like they should have their own sections. For example type mappings feels more like a reference and just doesn't make sense in the "creating components" section.

Maybe this isn't the right PR for this discussion, but it really might be more fitting to rename the "creating components" section to "Build a basic component" or something along those lines.

I'm happy to "just" convert the existing documentation 1:1 to work without cargo component, but IMO we really risk people getting lost/giving up in the middle of a very long introduction/getting started-ish page.

Resolves #319
Resolves #207

[vados-cosmonic]

Lots of discussion/help wanted here: @kate-goldenring @mkatychev @macovedj @itowlson .

In converting the current docs off of cargo component (since it's being deprecated), it really felt right to just leave the guide at creating the adder component. This is obviously a much larger change than first intended but I'd like to discuss it.

The goal is not to remove those other sections completely, but rather to move them to other parts of the book as necessary, and keep the initial component building relatively light/easy.

[kate-goldenring]

This is looking really close. Just some nits and help filling out a TODO

[kate-goldenring]

It looks like large sections of the rust guide were removed. Is there a reason for that? Can we retain that information on how to use interfaces, resources, and WIT types?

[vados-cosmonic]

After some discussion in the meeting today, there was general alignment on splitting out the more advanced stuff in the initial guide to other guides. Some things it might be good to do:

• Initially, combine some advanced functionality into the same new section
  • Maybe we can do this in stages with progressively smaller sections split out over time?
• If we can, have a dropdown of tutorial languages (so we avoid having 9 lines per split out tutorial)

Looks like we can do output.html.fold:
https://rust-lang.github.io/mdBook/format/configuration/renderers.html?utm_source=chatgpt.com#outputhtmlfold

[mkatychev]

After some discussion in the meeting today, there was general alignment on splitting out the more advanced stuff in the initial guide to other guides. Some things it might be good to do:

* Initially, combine some advanced functionality into the _same_ new section
  
  * Maybe we can do this in stages with progressively smaller sections split out over time?

* If we can, have a dropdown of tutorial languages (so we avoid having 9 lines per split out tutorial)

Looks like we can do output.html.fold: https://rust-lang.github.io/mdBook/format/configuration/renderers.html?utm_source=chatgpt.com#outputhtmlfold

That's quite a nice feature. @vados-cosmonic, would it be better to merge this as-is and follow up with the splitting to avoid a build up of merge conflicts?

[vados-cosmonic]

Ah good point @mkatychev -- I was hoping we could discuss this sooner and agree on the future direction (and maybe even get the changes in) but it may be quicker to do this ad-hoc and avoid piling up tons of merge conflicts.

[vados-cosmonic]

OK so conflicts have been addressed and created a new issue to track re-adding. Still a bit hesitant to merge this without the replacement/sketch of the future in place though... maybe we can give this just a little bit more and hopefully find time to flesh it out

[itowlson]

For what it's worth I'd be opposed to removing the "advanced" stuff without having replacement content in place, because that includes widely-needed things like resources. Happy to see those broken out into separate pages or whatever but I don't think we should just remove them with nothing in their place but an issue saying "put these back."

I appreciate I've not been following the discussion though!

[vados-cosmonic]

Hey @kate-goldenring @itowlson @mkatychev @macovedj thanks for the feedback so far!

I think at this point the refactor is ready for review. It's a lot to take in, but mostly I tried to:

• Move the deleted guides to new sections
• Remove/update mentions of cargo component

I'm fairly sure some sections don't quite work (i.e. the directions aren't perfect), BUT I'd like to get some feedback on:

• prose
• organization
• results of adding folding (and another layer of nesting!)

Unfortunately we don't have a preview environment set up, so you'll have to build the project locally to see what the output looks like w/ folding.

Here's a preview:

[vados-cosmonic]

Oh also @catamorphism would love feedback here if you have some cycles!

[kate-goldenring]

I really like the new layout. My main concern is how the JS language reference does not match the decided tutorial examples for explaining concepts and goes beyond the simple add example. What is our gameplan for that content?

[itowlson]

A few nits and typos but my main concerns are:

• I think the new proposed TOC structure is unhelpful, especially when the language guides are not closely aligned.
• There's some stuff in the "runnable components" section that didn't seem to line up and would probably benefit from a re-read to see if it's as you meant it.

Thanks for this epic effort!

[itowlson]

I am not sure "level of advancedness" is the best way to organise this. It requires the reader to guess if they are "building a simple component," "creating a runnable component," or "using a WIT resource" as their top-level piece of navigation. And then oh, I want to create a runnable component but I can't do that in JS?

I think for most readers this would work better with language as the top-level navigation. That way I can go "ooh, I know Rust" and then probe the subsections there for which fits, or "I know JS" and hey there's only one page so good times, I'll read that.

(I appreciate there are counter-arguments e.g. "okay I want to know how to use resources, okay that's only in Rust but maybe I can read that and figure out how to translate.")

[vados-cosmonic]

Thanks for pointing this out. The idea behind this reorganization was to focus the tutorials into specific sections that are focused on the action/concept we want to explain. The goal was to have focused sections related to different languages that explained a certain concept, and the concepts grouped together.

I'm certainly open to suggestions (ex. we could add numbering or some sort of order, or do some nesting), but I don't think the inverse (long language guides that tried to do many things, starting with building a simple component) works as it was easy to get lost in.

I think the vast majority of people will start with "building a simple component", because it's first, which is roughly equivalent to what we had before. The idea is that from there they'll see a short, focused guide to their language of choice, and be able to get an introduction to the necessary toolchain(s).

The point about people thinking that they can't do something in other languages is well taken -- I think adding an "Other Languages" section to all of them might be enough to ensure people don't get that impression.

[vados-cosmonic]

OK, so address the problem of people thinking that certain functionality isn't possible from their language, I've added generic "other languages" pages in 00a1b6f

[kate-goldenring]

A few more wording changes to lift up the other languages.

[vados-cosmonic]

Hey @kate-goldenring thanks for the review -- have addressed the comments and we should be really close to ready to go at least for the first version of this.

One thing I'm a little curious about is whether building-a-simple-component/other-languages.md should actually look like creating-runnable-components/other-languages.md.

I wonder if we should bother telling people to add to the list and rather just encourage them to create an issue and/or PR for their language that has support.

[kate-goldenring]

One thing I'm a little curious about is whether building-a-simple-component/other-languages.md should actually look like creating-runnable-components/other-languages.md.

Thanks for updating the building section. Yes my comment was intent to suggest all other-languages.md sections should be similarly worded to say "this is in progress -- please help".

I wonder if we should bother telling people to add to the list and rather just encourage them to create an issue and/or PR for their language that has support.

I am not sure i see the difference here between PR and "adding to the list" since one is prerequisite of the other

[vados-cosmonic]

Thanks for the reviews @kate-goldenring , @mkatychev -- I've added the suggestions and made some updates (replaced the last other-languages.md here)

[mkatychev]

LGTM this is definitely an improvement

[vados-cosmonic]

hey @itowlson would you mind taking a look here?

[kate-goldenring]

LGTM! Thank you for all this work with this refactor! It makes it much easier to add a language guide now that you can just add a section.