alexcrichton requested abrown for a review on PR #7987.
alexcrichton requested wasmtime-default-reviewers for a review on PR #7987.
alexcrichton opened PR #7987 from alexcrichton:refresh-docs
to bytecodealliance:main
:
I've gone through and done a pass over our current documentation and updated it in some both significant and minor ways. Changes made here are:
Old
WASI-*
documentation is all removed. This has been outdated for quite some time and WASI docs are best documented at https://github.com/WebAssembly/WASI nowadays.Language-specific documentation has all been removed. These docs have become pretty dated over the years and don't take into account many new developments in WASI or toolchains. This isn't the best place to document this anyway with excellent documentation existing elsewhere so it's all removed from here.
The CLI section of the book is now ordered just after the intro.
The "Governance" page under contributing is now removed as it's been "More coming soon ..." for a few years now.
Documentation under "Stability" and sub-pages has been updated. For example the release process is updated to reflect that branches are created on the 5th and published on the 20th.
Many WASI and WebAssembly proposals were moved to tier 1 as they're now stable proposals and fully supported in Wsamtime.
Winch is now explicitly listed as Tier 2 (wasn't mentioned before) for x86\_64 and Tier 3 for aarch64.
The WebAssembly
gc
proposal is now listed as Tier 3.Some miscellaneous documentation in the "platform support" section was updated.
<!--
Please make sure you include the following information:
If this work has been discussed elsewhere, please include a link to that
conversation. If it was discussed in an issue, just mention "issue #...".Explain why this change is needed. If the details are in an issue already,
this can be brief.Our development process is documented in the Wasmtime book:
https://docs.wasmtime.dev/contributing-development-process.htmlPlease ensure all communication follows the code of conduct:
https://github.com/bytecodealliance/wasmtime/blob/main/CODE_OF_CONDUCT.md
-->
fitzgen submitted PR review.
fitzgen submitted PR review.
fitzgen created PR review comment:
Eg wasmtime.dev has:
You can also download binaries directly from the GitHub Releases page.
fitzgen created PR review comment:
Alternatively, if we don't want these in the book, I think we should make an
examples
ortutorial
public submodule in thewasmtime
crate (cfg
'd for docs builds) that has these things.And we should still have a dedicated page in the book that links to the docs.rs docs for that submodule.
fitzgen created PR review comment:
Maybe worth linking to binary releases too, just to stave off the grumpy folks who don't like
curl | bash
.
fitzgen created PR review comment:
We still check that the associated examples compile in CI, so I'm not sure that getting rid of these is actually warranted? I feel like examples are the most useful form of non-API documentation and I think it would be a shame to just remove all of these. Maybe just keep the Rust versions?
The GCD examples, framed as GCD examples, don't really seem that useful but it is a simple example of the typed function API, which I think is valuable. Maybe we could reframe / retitle it or something?
The memory example seems useful.
The WASI example is dated. Definitely better places to go as far as toolchain docs go. But I think there is room for an example of how you call
add_to_linker
and all that with Wasmtime to consume WASI components (and probably also worth mentioning legazy preview1 stuff for a while, fwiw). We get a lot of issues filed by people not realizing they need to calladd_to_linker
and I think having an example to point people at would be good.The linking example is dated. Subsumed by component model stuff. But we might want to have an example of using the
Linker
and defining custom functions to be available for import.Language-specific debugging example seems redundant with the debugging section of the docs, although that section links to the Rust debugging bit. We should inline that into the debugging section (if you haven't already, haven't looked in detail at the rest of the changes yet).
Same thing for the language-specific core dumps bit.
The multi-value example seems like it is still generally useful.
pchickey submitted PR review.
pchickey created PR review comment:
I also feel the examples have some value and was planning on adding some more shortly.
pchickey edited PR review comment.
alexcrichton closed without merge PR #7987.
alexcrichton commented on PR #7987:
I'm gonna close this for now and I'll reopen if/when I get a chance to get back to it.
Last updated: Dec 23 2024 at 12:05 UTC