Comments (6)
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.
API
baz: String = foo(bar: String)
Convert a bar
into a baz
.
License
Apache-2.0
from wasm-pack.
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:
- If
--readme
flag is set use that file and put it inpkg/README.md
. - If
README_NPM.md
file exist use that file and put it inpkg/README.md
- If neither exist autogenerate
pkg/README.md
.
from wasm-pack.
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.
from wasm-pack.
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?
from wasm-pack.
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.)
from wasm-pack.
Oh, also I guess there is the question about media referenced in the Readme. 🤔
from wasm-pack.
Related Issues (20)
- Please export --crate-type on the command line HOT 1
- `wasm-pack fake` so CI tests and the like don't have to do any rust compilation HOT 1
- Multiple dependencies have critical defects identified by cargo-audit HOT 1
- After updating rustup, cannot build a project anymore HOT 2
- OS System Rust package pecularities cause wasm-pack build not to work on Quickstart from wasm-book HOT 2
- Cannot build project following tutorial HOT 5
- On a m1 mac with [email protected] installed, initializing the wasi module cases error HOT 2
- pick up `http_proxy` and `https_proxy` environment variables HOT 8
- wasm-pack does not understand overriden target-dir
- Found invalid metadata `core` `compiler_builtins` HOT 1
- Add an option to --keep-debug HOT 1
- wasm build failed because of rimage HOT 1
- Allow specifying url(s) for interactive browsers tests
- NPM Package Fails to Install on Mingw
- `wasm-pack test --headless --chrome` fails in docker container HOT 2
- Wasm-opt endless loop
- `wasm-pack` doesn't default-export the init function in .d.ts file HOT 1
- npm reports warnings in generated `package.json` file
- Support msys2 environment
- Please update the ring crate to 17.x HOT 2
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from wasm-pack.