Reorganize example documentation (#11757)

* Reorganize example documentation

This commit reorganizes example documentation in our online
documentation. The main changes here are:

* Chapter-per-language is now removed in favor of tabs-in-a-page for
  avoiding having the book be so large. Tabs are made with [mdbook-langtabs].
* Language-specific pages are all consolidated into a single page.
* Language-specific documentation now only mentions where to find docs
  instead of trying to document an intro for each language here.
* "Further examples" was folded into the main API section, meaning we
  just have one chapter of a lot of examples.

The main goal is to make the book less overwhelming from an example
perspective and ideally make it a bit easier to discover things. The
langtabs plugin is nice but not perfect, e.g. it doesn't support
`#`-anchors nor remembers which language you were looking at. Overall
though I feel this is still better than before.

[mdbook-langtabs]: https://github.com/nx10/mdbook-langtabs

* Fix typos

* Remove testing of mdbook from CI

Author: alexcrichton

.github/workflows/main.yml

@@ -282,8 +282,6 @@ jobs:
         echo "${{ runner.tool_cache }}/mdbook/bin" >> $GITHUB_PATH
         cargo install --root ${{ runner.tool_cache }}/mdbook --version ${{ env.CARGO_MDBOOK_VERSION }} mdbook --locked
     - run: (cd docs && mdbook build)
-    - run: cargo build -p wasi-common --features wasmtime/wat,wasmtime/cranelift
-    - run: (cd docs && mdbook test -L ../target/debug/deps)
 
     # Build Rust API documentation.
     #

docs/SUMMARY.md

@@ -7,54 +7,21 @@
   - [CLI Logging](./cli-logging.md)
   - [Cache Configuration](./cli-cache.md)
 - [Using the Wasmtime API](./lang.md)
-  - [Rust](./lang-rust.md)
-    - [Hello, world!](./examples-rust-hello-world.md)
-    - [Calculating the GCD](./examples-rust-gcd.md)
-    - [Using Linear Memory](./examples-rust-memory.md)
-    - [WASIp2](./examples-rust-wasip2.md)
-    - [Linking Modules](./examples-rust-linking.md)
-    - [Debugging](./examples-rust-debugging.md)
-    - [Core Dumps](./examples-rust-core-dumps.md)
-    - [Using Multi-Value](./examples-rust-multi-value.md)
-    - [`anyref` Reference Type](./examples-rust-anyref.md)
-    - [`externref` Reference Type](./examples-rust-externref.md)
-    - [Multiple Memories](./examples-rust-multimemory.md)
-    - [Serializing Modules](./examples-rust-serialize.md)
-    - [Multithreaded Embedding](./examples-rust-multithreaded-embedding.md)
-    - [Memory Protection Keys](./examples-rust-mpk.md)
-  - [C](./lang-c.md)
-    - [Hello, World!](./examples-c-hello-world.md)
-    - [Calculating the GCD](./examples-c-gcd.md)
-    - [Using Linear Memory](./examples-c-memory.md)
-    - [WASIp1](./examples-c-wasi.md)
-    - [Linking Modules](./examples-c-linking.md)
-    - [Debugging](./examples-c-debugging.md)
-    - [Using Multi-Value](./examples-c-multi-value.md)
-    - [`anyref` Reference Type](./examples-c-anyref.md)
-    - [`externref` Reference Type](./examples-c-externref.md)
-    - [Multiple Memories](./examples-c-multimemory.md)
-    - [Serializing Modules](./examples-c-serialize.md)
-    - [Multithreaded Embedding](./examples-c-multithreaded-embedding.md)
-  - [C++](./lang-cpp.md)
-    - [Hello, World!](./examples-cpp-hello-world.md)
-    - [Calculating the GCD](./examples-cpp-gcd.md)
-    - [Using Linear Memory](./examples-cpp-memory.md)
-    - [WASIp1](./examples-cpp-wasi.md)
-    - [Linking Modules](./examples-cpp-linking.md)
-    - [Using Multi-Value](./examples-cpp-multi-value.md)
-    - [`anyref` Reference Type](./examples-cpp-anyref.md)
-    - [`externref` Reference Type](./examples-cpp-externref.md)
-    - [Multiple Memories](./examples-cpp-multimemory.md)
-    - [Serializing Modules](./examples-cpp-serialize.md)
-    - [Multithreaded Embedding](./examples-cpp-multithreaded-embedding.md)
-    - [Async Host Functions](./examples-cpp-async.md)
-  - [Python](./lang-python.md)
-  - [.NET](./lang-dotnet.md)
-  - [Go](./lang-go.md)
-  - [Bash](./lang-bash.md)
-  - [Ruby](./lang-ruby.md)
-  - [Elixir](./lang-elixir.md)
-- [Further Examples](./examples.md)
+  - [Hello, world!](./examples-hello-world.md)
+  - [Calculating the GCD](./examples-gcd.md)
+  - [Using Linear Memory](./examples-memory.md)
+  - [Linking Modules](./examples-linking.md)
+  - [`anyref` Reference Type](./examples-anyref.md)
+  - [`externref` Reference Type](./examples-externref.md)
+  - [Multiple Memories](./examples-multimemory.md)
+  - [Using Multi-Value](./examples-multi-value.md)
+  - [Serializing Modules](./examples-serialize.md)
+  - [Multithreaded Embedding](./examples-multithreaded-embedding.md)
+  - [WASIp1](./examples-wasip1.md)
+  - [WASIp2](./examples-wasip2.md)
+  - [Core Dumps](./examples-core-dumps.md)
+  - [Memory Protection Keys](./examples-mpk.md)
+  - [Async Host Functions](./examples-async.md)
   - [Debugging WebAssembly](./examples-debugging.md)
     - [Debugging with `gdb` and `lldb`](./examples-debugging-native-debugger.md)
     - [Debugging with Core Dumps](./examples-debugging-core-dumps.md)

docs/book.toml

@@ -5,7 +5,70 @@ src = "."
 title = "Wasmtime"
 
 [output.html]
-additional-js = ["js/moment.min.2.30.1.js", "js/mermaid.min.11.6.0.js", "js/index.js"]
+additional-js = [
+  "js/moment.min.2.30.1.js",
+  "js/mermaid.min.11.6.0.js",
+  "js/index.js",
+  "js/langtabs.js",
+]
 cname = "docs.wasmtime.dev"
 git-repository-url = "https://github.com/bytecodealliance/wasmtime"
 edit-url-template = "https://github.com/bytecodealliance/wasmtime/edit/main/docs/{path}"
+additional-css = ["css/langtabs.css"]
+
+[output.html.redirect]
+"/examples-c-anyref.html" = "/examples-anyref.html"
+"/examples-c-debugging.html" = "/examples-debugging.html"
+"/examples-c-externref.html" = "/examples-externref.html"
+"/examples-c-gcd.html" = "/examples-gcd.html"
+"/examples-c-hello-world.html" = "/examples-hello-world.html"
+"/examples-c-linking.html" = "/examples-linking.html"
+"/examples-c-memory.html" = "/examples-memory.html"
+"/examples-c-multi-value.html" = "/examples-multi-value.html"
+"/examples-c-multimemory.html" = "/examples-multimemory.html"
+"/examples-c-multithreaded-embedding.html" = "/examples-multithreaded-embedding.html"
+"/examples-c-serialize.html" = "/examples-serialize.html"
+"/examples-c-wasi.html" = "/examples-wasip1.html"
+
+"/examples-cpp-anyref.html" = "/examples-anyref.html"
+"/examples-cpp-debugging.html" = "/examples-debugging.html"
+"/examples-cpp-externref.html" = "/examples-externref.html"
+"/examples-cpp-gcppd.html" = "/examples-gcppd.html"
+"/examples-cpp-hello-world.html" = "/examples-hello-world.html"
+"/examples-cpp-linking.html" = "/examples-linking.html"
+"/examples-cpp-memory.html" = "/examples-memory.html"
+"/examples-cpp-multi-value.html" = "/examples-multi-value.html"
+"/examples-cpp-multimemory.html" = "/examples-multimemory.html"
+"/examples-cpp-multithreaded-embedding.html" = "/examples-multithreaded-embedding.html"
+"/examples-cpp-serialize.html" = "/examples-serialize.html"
+"/examples-cpp-wasi.html" = "/examples-wasip1.html"
+"/examples-cpp-async.html" = "/examples-async.html"
+
+"/examples-rust-anyref.html" = "/examples-anyref.html"
+"/examples-rust-debugging.html" = "/examples-debugging.html"
+"/examples-rust-externref.html" = "/examples-externref.html"
+"/examples-rust-grustd.html" = "/examples-grustd.html"
+"/examples-rust-hello-world.html" = "/examples-hello-world.html"
+"/examples-rust-linking.html" = "/examples-linking.html"
+"/examples-rust-memory.html" = "/examples-memory.html"
+"/examples-rust-multi-value.html" = "/examples-multi-value.html"
+"/examples-rust-multimemory.html" = "/examples-multimemory.html"
+"/examples-rust-multithreaded-embedding.html" = "/examples-multithreaded-embedding.html"
+"/examples-rust-serialize.html" = "/examples-serialize.html"
+"/examples-rust-wasip2.html" = "/examples-wasip2.html"
+"/examples-rust-wasi.html" = "/examples-wasip1.html"
+"/examples-rust-wasip1.html" = "/examples-wasip1.html"
+"/examples-rust-core-dumps.html" = "/examples-core-dumps.html"
+"/examples-rust-mpk.html" = "/examples-mpk.html"
+
+"/lang-rust.html" = "/lang.html#rust"
+"/lang-c.html" = "/lang.html#c"
+"/lang-bash.html" = "/lang.html#bash"
+"/lang-python.html" = "/lang.html#python"
+"/lang-go.html" = "/lang.html#go"
+"/lang-dotnet.html" = "/lang.html#net"
+"/lang-ruby.html" = "/lang.html#ruby"
+"/lang-elixir.html" = "/lang.html#elixir"
+
+[preprocessor.langtabs]
+command = "mdbook-langtabs"

docs/css/langtabs.css

@@ -0,0 +1,136 @@
+.langtabs {
+  margin: 0.5em 0 1.5em 0;
+  font-family: var(--fonts);
+}
+
+.langtabs-header {
+  display: flex;
+  overflow-x: auto;
+  gap: 0.25rem;
+  border-bottom: 1px solid var(--icons);
+  padding-bottom: 1px;
+  margin-bottom: -1px;
+  position: relative;
+  z-index: 2;
+}
+
+.langtabs-header {
+  -webkit-overflow-scrolling: touch;
+  scrollbar-width: none; /* Firefox */
+}
+
+.langtabs-header::-webkit-scrollbar {
+  display: none; /* Chrome, Safari, Edge */
+}
+
+.langtabs-tab {
+  padding: 0.6rem 1.1rem;
+  background: none;
+  border: 1px solid transparent;
+  border-bottom: none;
+  border-top-left-radius: 4px;
+  border-top-right-radius: 4px;
+  cursor: pointer;
+  white-space: nowrap;
+  display: flex;
+  align-items: center;
+  gap: 0.7rem;
+  color: var(--text);
+  font-size: 1.2rem;
+  font-weight: 400;
+  transition: all 0.15s ease;
+  position: relative;
+  top: 1px;
+}
+
+.langtabs-tab:hover {
+  color: var(--links);
+  background-color: rgba(0, 0, 0, 0.03);
+}
+
+.langtabs-tab.active {
+  color: var(--links); /* Use theme link color */
+  border-color: var(--icons);
+  border-bottom: 1px solid var(--bg);
+  background-color: var(--bg);
+  font-weight: 500;
+}
+
+.langtabs-icon {
+  width: 1.4em;
+  height: 1.4em;
+  font-size: 1.4em;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+}
+
+/* inactive tabs use text color, active tabs use theme link color */
+.langtabs-tab .langtabs-icon {
+  color: inherit;
+  opacity: 0.8;
+}
+
+.langtabs-tab.active .langtabs-icon {
+  color: var(--links); /* Use theme link color */
+  opacity: 1;
+}
+
+.langtabs-content {
+  position: relative;
+  border: 1px solid var(--icons);
+  border-radius: 3px;
+  border-top-left-radius: 0;
+  overflow: hidden;
+}
+
+.langtabs-code {
+  display: none;
+}
+
+.langtabs-code.active {
+  display: block;
+}
+
+/* CodeBlock styling to match mdBook */
+.langtabs-code pre {
+  margin: 0;
+  padding: 0;
+  background-color: var(--bg);
+}
+
+.langtabs-code pre code {
+  display: block;
+  padding: 1rem;
+  overflow-x: auto;
+  font-family: var(--mono-font);
+  font-size: 0.85em;
+  line-height: 1.5;
+}
+
+@media print {
+  .langtabs-tab:not(.active) {
+    display: none;
+  }
+  
+  .langtabs-content {
+    border: 1px solid #ddd;
+  }
+  
+  .langtabs-code.active {
+    display: block !important;
+  }
+}
+
+@media (max-width: 640px) {
+  .langtabs-tab {
+    padding: 0.5rem 0.8rem;
+    font-size: 1.1rem;
+  }
+  
+  .langtabs-icon {
+    font-size: 1.3em;
+    width: 1.3em;
+    height: 1.3em;
+  }
+}

docs/examples-anyref.md

@@ -0,0 +1,34 @@
+# Working with `anyref`
+
+You can also browse this source code online and clone the wasmtime
+repository to run the example locally:
+
+* [Rust](https://github.com/bytecodealliance/wasmtime/blob/main/examples/anyref.rs)
+* [C](https://github.com/bytecodealliance/wasmtime/blob/main/examples/anyref.c)
+* [C++](https://github.com/bytecodealliance/wasmtime/blob/main/examples/anyref.cc)
+
+This example demonstrates using `anyref` values.
+
+## Wasm Source
+
+```wat
+{{#include ../examples/anyref.wat}}
+```
+
+## Host Source
+
+<!-- langtabs-start -->
+
+```rust
+{{#include ../examples/anyref.rs}}
+```
+
+```c
+{{#include ../examples/anyref.c}}
+```
+
+```cpp
+{{#include ../examples/anyref.cc}}
+```
+
+<!-- langtabs-end -->

docs/examples-cpp-async.md renamed to docs/examples-async.md

@@ -7,14 +7,18 @@ repository to run the example locally.
 
 This example demonstrates configuring Wasmtime for asynchronous operation and calling async host functions from wasm.
 
-## `async.wat`
+## Wasm Source
 
 ```wat
 {{#include ../examples/async.wat}}
 ```
 
-## `async.cpp`
+## Host Source
+
+<!-- langtabs-start -->
 
 ```cpp
 {{#include ../examples/async.cpp}}
 ```
+
+<!-- langtabs-end -->