docs: Clarify setup for "Rust Components" tutorial #218
Conversation
| a + b | ||
| } | ||
| } | ||
| {{#include ../../examples/tutorial/adder/src/lib.rs}} |
There was a problem hiding this comment.
Not against reverting the #includes, the tradeoff here is that the raw markdown is less readable but this will likely result in less code drift overall.
There was a problem hiding this comment.
I like the includes -- certainly saves us time 👍
|
Hey @mkatychev would you mind taking another look at this? One of the thing we've wanted to do for a bit was refactor to use the same WIT files everywhere, and we finally have that in now for all the guides -- I think the changes here are in conflict with that, but it should simplify your diff as well. |
|
|
||
| ## 5. Implement the generated `Guest` trait | ||
| ## Implementing the `Guest` trait |
There was a problem hiding this comment.
@vados-cosmonic I've removed the numbering for the headers to simplify anchor link generation, happy to add them back in.
There was a problem hiding this comment.
I'd love feedback from @kate-goldenring here -- I think it's mostly a style thing. I think numbers help people refer to steps (ex. "please see step 3") but I could definitely go the other way.
That said, if we want to remove the numbers here, we should remove them everywhere (which isn't a hard change either, happy to help here or in a follow up if you'd rather not do it).
Thanks for working on this! 🙇
There was a problem hiding this comment.
Sounds good, I was mostly following style patterns off of the rust book, including using present continuous tense for titles, ex: including v.s. include.
There was a problem hiding this comment.
Yeah this makes sense... Maybe what we want is actually demarcation at a higher level (ex. in the Rust book the sections are clearly demarcated in the ToC on the left), then we can go with continuous tense and still be able to refer to things?
Happy either way here, I think the Rust book is an excellent example to follow so maybe we should change to look more like them, even if I'm partial to "steps".
There was a problem hiding this comment.
Would you mind elaborating in your 'including demarcation' comment?
There was a problem hiding this comment.
Ah I was referring to this style of numbering in the Rust book:
So when someone wants to mention a specific section they can refer "Section 3.3"
There was a problem hiding this comment.
I looked into this a bit and it looks like adding subchapters based on anchor links is still an open issue:
rust-lang/mdBook#167
the component docs currently use numbered subchapters, however they're currently broken up by language:
We could break up the subchapters into their own markdown page so for example src/language-support/rust-scaffolding-component.md would become:
8.6.1 Scaffolding a Component
There was a problem hiding this comment.
Another problem with having numbered headers is that any external references to the section (such as https://component-model.bytecodealliance.org/language-support/rust.html#6-build-the-component) will become broken if the section gets reordered. I wonder if there's a cleaner way of doing header numbering in the same way as numbered lists where the numbering gets automatically reordered:
1. installing
1. scaffolding
1. building
1. running
Codeblock above produces this:
- installing
- scaffolding
- building
- running
There was a problem hiding this comment.
Hmnnn OK, rather than make any large changes in this PR, let's maintain consistency at least then discuss it -- It looks like there are a bunch of options here, and we're probably not the only two people who want to chat it out!
|
|
||
| ```console |
There was a problem hiding this comment.
console langtype seems to produce less syntax highlighting than sh.
There was a problem hiding this comment.
yeah so my stance on that is that writing into a console is not normally syntax highlighted either, so it matches.
If we have a shell script, or a bash script, then it makes sense to use those, but my stance here is that if it's a console command you're supposed to enter there are other ways to make it more readable:
something \
--like this \
--rather-than console
and if it's code, then it should be highlighted.
There was a problem hiding this comment.
I've done it in this PR: #232
mkatychev
changed the title
| @@ -1,13 +1,14 @@ | |||
| #[allow(warnings)] | |||
| mod bindings; | |||
|
|
|||
| // Separating out the interface puts it in a sub-module | |||
There was a problem hiding this comment.
I'm not sure this comment makes sense, because someone coming to this would probably think "as opposed to what?" and we don't have an example of exporting the function directly anymore.
Maybe this comment could be expanded to a more general statement about bindings pathing (explaining the module hierarchy a little bit -- exports because it's an export, docs being the namepace, adder being the package, etc)
|
|
||
| ## 5. Implement the generated `Guest` trait | ||
| ## Implementing the `Guest` trait |
There was a problem hiding this comment.
Hmnnn OK, rather than make any large changes in this PR, let's maintain consistency at least then discuss it -- It looks like there are a bunch of options here, and we're probably not the only two people who want to chat it out!
|
|
||
| ```console | ||
| ```sh |
There was a problem hiding this comment.
console here -- I believe this was the change you made in the other PR as well
| } | ||
| We now need to change our generated `wit/world.wit` to match `docs:adder`: | ||
| ```wit | ||
| {{#include ../../examples/tutorial/wit/adder/world.wit}} |
There was a problem hiding this comment.
Fantastic, this will save a ton of work!
| cargo component build --release | ||
| ``` | ||
|
|
||
| You can use `wasm-tools component wit` to output the WIT package of the component: | ||
| You can use `wasm-tools` to inspect the WIT package generated by `cargo-component`: |
There was a problem hiding this comment.
This isn't quite right -- we're actually inspecting the built component itself, which happens to contain the WIT that was used to create it. I think the old wording was right here.
|
|
||
| To verify that our component works, lets run it from a Rust application that knows how to run a | ||
| component targeting the [`adder` world][adder-wit]. | ||
| component targeting the [`docs:adder/adder`](#adding-the-wit-world) world. |
There was a problem hiding this comment.
I'm not sure being explicit about the namespace and package herehelps -- not everyone knows the more qualified naming schemes for WIT interfaces. Someone might think "what is the docs:adder/adder world?", and in the linked section we refer to it just as docs:adder (no mention of the world).
I think we want people to think in terms of worlds, which import/export interfaces -- the namespace and package are much less important IMO.
| a + b | ||
| } | ||
| } | ||
| {{#include ../../examples/tutorial/adder/src/lib.rs}} |
There was a problem hiding this comment.
I like the includes -- certainly saves us time 👍
This PR aims to make explicit some assumptions made in the Rust Components tutorial.
Changes made to
component-model/src/language-support/rust.md:example:component/exampleto help disambiguate between similar sounding names such asaddandaddercomponent-docs/component-model/src/language-support/rust.md
Lines 51 to 53 in 2e207e4
$from shell commands to make them easier to copy