Wasm-pack: Example usage documentation

[mgattozzi]

While my tutorial over on rust-wasm hasn't landed in the book yet it will soonish. However, we want people to be able to reference something a little less longform as well because sometimes all you need is a few words describing how to use the tool.

We should make docs that are short like the readme but explain things like using the scope flag etc. Also maybe even use asciinema to show some visual examples for people!

[mgattozzi]

The tutorial did land and is available here. This is still open and is not too hard to document. If you're looking for an easy contribution that helps others this is it!

Will provide in depth mentoring instructions for each of these, just let me know what you're interested in! Things that need to be documented:

• [ ] wasm-pack init
• [ ] wasm-pack pack
• [ ] wasm-pack publish

As well as other optional flags such as:

• [ ] scope for wasm-pack init

Optional Arguments:

• [ ] path arguments

[ashleygwilliams]

i'd also add the path argument to this list as well!

[mgattozzi]

I updated the list! :D

[data-pup]

I would love to help with this one :) I can start with the init command and move from there.

[mgattozzi]

Awesome @data-pup! Here's what you'll need to do:

• Create a folder called docs in the top level directory
• Create a file called init.md inside the docs directory
• In that file type up some instructions on how it works
• You should also mention the scope flag and optional path argument for it as well

This should be a good start for this.

I think we can then possibly later include them in the source code for a rustdoc build. Since we're on nightly anyways for the forseeable future we can use the doc_include feature in another PR to include what you write up as docs :) That's a little outside the scope of this issue now so don't worry about it.

Once you've got a good basis put in a PR and we can polish it up then merge it :D

[data-pup]

Sounds good! Thank you for the instructions, I will get started on that today. I will follow up if I have any questions 🙂

[mgattozzi]

@data-pup Sweet! :D

[data-pup]

I have a question about the scope flag mentioned here. If we run the command wasm-pack init --scope HELLO, is that defining the npm package name as HELLO? The tutorial page above mentions that this is needed so that the name does not conflict with an existing wasm-add package. Thanks!

Update: I did some reading on this, I think I have a better understanding of it now. Pardon.

[mgattozzi]

Hey @data-pup in case it wasn't clear it'll name the package as:
HELLO/your_rust_package_name

Without the scope flag it's just the package name

[mgattozzi]

@data-pup made some great first steps. I think we could expand this out with gifs and things showing how to use it. Some people are more visual than text. Video tutorials might also be fun.

[data-pup]

Yeah! I was thinking about that too. I really like the gif in the readme, what was used to make that? Adding a gif demonstrating each command wouldn't be too hard :)

[mgattozzi]

@ashleygwilliams came up with it so she can probably explain what that process was

[ashleygwilliams]

@data-pup i used https://asciinema.org/ and then https://github.com/asciinema/asciicast2gif -- it is a SLOW process, and a little buggy, but a lot of fun- would love to see some more gifs!

[ashleygwilliams]

@data-pup are you still interested in doing some gifs? i think we'd be super into it! (need to get #145 fixed, but after that...)

@mgattozzi what else were you expecting to be done for this issue? it might be useful to close this and open more specific ones...

[mgattozzi]

Yeah I'd say we could close this for now and I can open up more specific ones, like expanded tutorials, gifs etc. at a later date.

[data-pup]

Bandwidth is slightly thin for me at the moment, (focused on some twiggy stuff atm) but I would definitely be open to coming back to these in the near future. I think @mgattozzi is right, we could open issues for specific usage documentation tasks later on.

[mgattozzi]

Since all the original stuff mentioned was covered I'm going to close this then and open specific issues later.