Generated documentation in READMEs

[ashleygwilliams]

in generating an npm package from a rust/wasm project do we anticipate that the author would want to reuse the README from the rust crate or create a new one?

[yoshuawuyts]

I'm thinking ideally we could generate a README. In JS land READMEs are usually some metadata + statement of intent + API documentation.

Most of the metadata can probably be extracted from Cargo.toml. API docs can probably be generated from the generated code. Because it's typescript, we can probably also find the signatures (although this probably requires some patches). Statement of intent might need some human intervention (e.g. allow passing a markdown snippet), but just including the project description should be fine I reckon?

E.g. output would look somewhat like this:

---

bar-to-baz-wasm

Convert bars into bazzi. WebAssembly bindings generated using wasm-pack.

• Repository
• Rust Documentation

API

baz: String = foo(bar: String)

Convert a bar into a baz.

License

Apache-2.0

[ashleygwilliams]

this is a great suggestion @yoshuawuyts - i really like it! do you think creating a separate crate to handle taking rustdoc generation -> markdown file would be useful? then we could just integrate it in here. seems like a vaguely big enough job that it warrants another crate. thoughts?

[ootoovak]

I personally like README files that help guide new people into explaining what the intent of the library is how though some simple to slightly more complex examples. Then either a list of or links off to some API docs. Not to mention any other human / ecosystem related information.

In that people centric sense I think auto file generation could help but I personally would also like the option to have hand written parts (or the whole file) as well.

So, if the pkg folder is considered ephemeral what I was thinking is that developers could either write a README_NPM.md file that gets automatically pulled into pkg and renamed or there is an argument you could pass into the build command where you could specify which file you want to pull in as a NPM README like wasm-pack build --readme=README_WASM.md or something.

Perhaps there is room for all options?

A possible order:

1. If --readme flag is set use that file and put it in pkg/README.md.
2. If README_NPM.md file exist use that file and put it in pkg/README.md
3. If neither exist autogenerate pkg/README.md.

[ootoovak]

For now I might try method 2 manually in my crate and see if I find much duplication between the READMEs. (Rightly or wrongly I am aiming to have my crate usable by both Rust and JS.)

[ootoovak]

Oh, also I guess there is the question about media referenced in the Readme. 🤔

[ghost]

Is there any update about this? I like both ideas, from @yoshuawuyts and @ootoovak.

In my case the same crate can be used itself as Cargo dependency and publish it as NPM dependency, but the README.md for Rust crate is not useful for NPM package or I need to write both together.