From 2a6e82d5f05fe3eb8bcdca53a89ff94e46151a3e Mon Sep 17 00:00:00 2001 From: Luke Chu <37006668+lukechu10@users.noreply.github.com> Date: Sat, 11 Sep 2021 19:00:44 -0700 Subject: [PATCH] Organize docs (#236) * Update docs * Fix missing period --- docs/build.rs | 6 ++- docs/next/advanced/advanced_reactivity.md | 49 ------------------ docs/next/advanced/contexts.md | 48 +++++++++++++++++ docs/next/advanced/optimize_wasm_size.md | 51 +++++++++++++++++++ docs/next/contribute/development.md | 2 +- docs/next/getting_started/installation.md | 2 +- docs/next/optimizations/code_size.md | 5 -- docs/next/optimizations/speed.md | 5 -- docs/next/sidebar.json | 17 +++---- .../v0.5/contribute/development.md | 2 +- .../v0.5/getting_started/installation.md | 2 +- examples/ssr/index.html | 3 +- website/sitemap_index.xml | 4 +- 13 files changed, 116 insertions(+), 80 deletions(-) create mode 100644 docs/next/advanced/contexts.md create mode 100644 docs/next/advanced/optimize_wasm_size.md delete mode 100644 docs/next/optimizations/code_size.md delete mode 100644 docs/next/optimizations/speed.md diff --git a/docs/build.rs b/docs/build.rs index 1c8e9c850..ada1e5859 100644 --- a/docs/build.rs +++ b/docs/build.rs @@ -72,8 +72,10 @@ fn parse(path: &Path) -> Result> { l.children.push(tmp); } Some(Event::Html(CowStr::from(format!( - "{}", - level, anchor, name, level + "{name}", + level = level, + anchor = anchor, + name = name )))) } } diff --git a/docs/next/advanced/advanced_reactivity.md b/docs/next/advanced/advanced_reactivity.md index 5c96e1431..7547c9155 100644 --- a/docs/next/advanced/advanced_reactivity.md +++ b/docs/next/advanced/advanced_reactivity.md @@ -1,54 +1,5 @@ # Advanced Reactivity -## Contexts - -Contexts provide an easy way to share data between components without drilling props through -multiple levels of the component hierarchy. - -Creating a `ContextProvider` is required before any components can use the context. The value used -should implement `Clone`. - -### Using `ContextProvider` - -`ContextProvider` is a component like any other. It takes a `value` prop which is the context value -and a `children` prop which is the child components that have access to the context value. - -### Using `use_context` - -`use_context` returns a clone of the value for a context of a given type. - -### Example - -```rust -use sycamore::prelude::*; -use sycamore::context::{ContextProvider, ContextProviderProps, use_context}; - -#[derive(Clone)] -struct Counter(Signal); - -#[component(CounterView)] -fn counter_view() -> Template { - let counter = use_context::(); - - template! { - (counter.0.get()) - } -} - -template! { - ContextProvider(ContextProviderProps { - value: Counter(Signal::new(0)), - children: || template! { - CounterView() - } - }) -} -``` - -Remember that unlike contexts in React and many other libraries, the `value` prop is not reactive by -itself. This is because components only run once. In order to make a context value reactive, you -need to use a `Signal` or other reactive data structure. - ## Reactive scopes ### on_cleanup diff --git a/docs/next/advanced/contexts.md b/docs/next/advanced/contexts.md new file mode 100644 index 000000000..9fc1975d0 --- /dev/null +++ b/docs/next/advanced/contexts.md @@ -0,0 +1,48 @@ +# Contexts + +Contexts provide an easy way to share data between components without drilling props through +multiple levels of the component hierarchy. + +Creating a `ContextProvider` is required before any components can use the context. The value used +should implement `Clone`. + +## Using `ContextProvider` + +`ContextProvider` is a component like any other. It takes a `value` prop which is the context value +and a `children` prop which is the child components that have access to the context value. + +## Using `use_context` + +`use_context` returns a clone of the value for a context of a given type. + +## Example + +```rust +use sycamore::prelude::*; +use sycamore::context::{ContextProvider, ContextProviderProps, use_context}; + +#[derive(Clone)] +struct Counter(Signal); + +#[component(CounterView)] +fn counter_view() -> Template { + let counter = use_context::(); + + template! { + (counter.0.get()) + } +} + +template! { + ContextProvider(ContextProviderProps { + value: Counter(Signal::new(0)), + children: || template! { + CounterView() + } + }) +} +``` + +Remember that unlike contexts in React and many other libraries, the `value` prop is not reactive by +itself. This is because components only run once. In order to make a context value reactive, you +need to use a `Signal` or other reactive data structure. diff --git a/docs/next/advanced/optimize_wasm_size.md b/docs/next/advanced/optimize_wasm_size.md new file mode 100644 index 000000000..f116aaaa5 --- /dev/null +++ b/docs/next/advanced/optimize_wasm_size.md @@ -0,0 +1,51 @@ +# Reducing binary size + +**Note**: More information about reducing binary size can be found in the +[Rust Wasm Book](https://rustwasm.github.io/book/reference/code-size.html#optimizing-builds-for-code-size). + +## Building in release mode + +A common mistake when building a Wasm binary is to forget to build in release mode. If you are using +`trunk`, simply add the `--release` flag to the build command: + +```bash +trunk build --release +``` + +## `wee_alloc` + +[`wee_alloc`](https://github.com/rustwasm/wee_alloc) is a memory allocator focused on targeting +WebAssembly, producing a small .wasm code size, and having a simple, correct implementation. +Replacing the default allocator with this one will result in a smaller binary size at the expense of +speed and memory overhead. + +```rust +// Use `wee_alloc` as the global allocator. +#[global_allocator] +static ALLOC: wee_alloc::WeeAlloc = wee_alloc::WeeAlloc::INIT; +``` + +## `Cargo.toml` + +It is possible to configure release builds to be smaller by using various flags and configurations +in your `Cargo.toml` file. + +```toml +[profile.release] +# Do not perform backtrace for panic on release builds. +panic = 'abort' +# Perform optimizations on all codegen units. +codegen-units = 1 +# Optimize for size. +opt-level = 's' # or 'z' to optimize "aggressively" for size +# Enable link time optimization. +lto = true +``` + +## `wasm-opt` + +If you are using `trunk`, add this line to your `index.html` to enable `wasm-opt`: + +```html + +``` diff --git a/docs/next/contribute/development.md b/docs/next/contribute/development.md index ee403432b..1d92a1de1 100644 --- a/docs/next/contribute/development.md +++ b/docs/next/contribute/development.md @@ -19,7 +19,7 @@ cd sycamore ## Testing -To run unit tests and non WASM integration tests, use: +To run unit tests and non Wasm integration tests, use: ```bash cargo test diff --git a/docs/next/getting_started/installation.md b/docs/next/getting_started/installation.md index 95f5ed021..c12fbfc9d 100644 --- a/docs/next/getting_started/installation.md +++ b/docs/next/getting_started/installation.md @@ -23,7 +23,7 @@ version of Rust. [Trunk](https://trunkrs.dev) is the recommended build tool for Sycamore. If you are from JS land, Trunk is like [webpack](https://webpack.js.org/) or [rollup](https://rollupjs.org/) but specifically -tailored towards Rust + WASM apps. +tailored towards Rust + Wasm apps. You can use the following command to install Trunk: diff --git a/docs/next/optimizations/code_size.md b/docs/next/optimizations/code_size.md deleted file mode 100644 index dff303cd7..000000000 --- a/docs/next/optimizations/code_size.md +++ /dev/null @@ -1,5 +0,0 @@ -# Optimize for Code Size - -TODO - -Help us out by writing the docs and sending us a PR! diff --git a/docs/next/optimizations/speed.md b/docs/next/optimizations/speed.md deleted file mode 100644 index a52536e85..000000000 --- a/docs/next/optimizations/speed.md +++ /dev/null @@ -1,5 +0,0 @@ -# Optimize for Speed - -TODO - -Help us out by writing the docs and sending us a PR! diff --git a/docs/next/sidebar.json b/docs/next/sidebar.json index f4ecd7546..219e0687d 100644 --- a/docs/next/sidebar.json +++ b/docs/next/sidebar.json @@ -57,6 +57,10 @@ "name": "Tweened", "href": "advanced/tweened" }, + { + "name": "Contexts", + "href": "advanced/contexts" + }, { "name": "Advanced Reactivity", "href": "advanced/advanced_reactivity" @@ -80,19 +84,10 @@ { "name": "JS Interop", "href": "advanced/js_interop" - } - ] - }, - { - "title": "Optimizations", - "items": [ - { - "name": "Code Size", - "href": "optimizations/code_size" }, { - "name": "Speed", - "href": "optimizations/speed" + "name": "Optimize Wasm Size", + "href": "advanced/optimize_wasm_size" } ] }, diff --git a/docs/versioned_docs/v0.5/contribute/development.md b/docs/versioned_docs/v0.5/contribute/development.md index ee403432b..1d92a1de1 100644 --- a/docs/versioned_docs/v0.5/contribute/development.md +++ b/docs/versioned_docs/v0.5/contribute/development.md @@ -19,7 +19,7 @@ cd sycamore ## Testing -To run unit tests and non WASM integration tests, use: +To run unit tests and non Wasm integration tests, use: ```bash cargo test diff --git a/docs/versioned_docs/v0.5/getting_started/installation.md b/docs/versioned_docs/v0.5/getting_started/installation.md index 79978ae5f..a882741c5 100644 --- a/docs/versioned_docs/v0.5/getting_started/installation.md +++ b/docs/versioned_docs/v0.5/getting_started/installation.md @@ -18,7 +18,7 @@ rustup target add wasm32-unknown-unknown [Trunk](https://trunkrs.dev) is the recommended build tool for Sycamore. If you are from JS land, Trunk is like [webpack](https://webpack.js.org/) or [rollup](https://rollupjs.org/) but specifically -tailored to Rust + WASM apps. +tailored to Rust + Wasm apps. You can use `cargo` to install Trunk: diff --git a/examples/ssr/index.html b/examples/ssr/index.html index e06536450..a5ef7ca50 100644 --- a/examples/ssr/index.html +++ b/examples/ssr/index.html @@ -12,7 +12,6 @@ - This example does not run in WASM. You must run it locally with "cargo run - --example ssr". + This example does not run in Wasm. You must run it locally with "cargo run". diff --git a/website/sitemap_index.xml b/website/sitemap_index.xml index e10658c90..fadb6e460 100644 --- a/website/sitemap_index.xml +++ b/website/sitemap_index.xml @@ -5,9 +5,11 @@ https://sycamore-rs.netlify.app/versionsmonthly0.3 https://sycamore-rs.netlify.app/news/announcing-v0.5.0yearly0.8 https://sycamore-rs.netlify.app/docs/advanced/advanced_reactivityweekly0.5 +https://sycamore-rs.netlify.app/docs/advanced/contextsweekly0.5 https://sycamore-rs.netlify.app/docs/advanced/cssweekly0.5 https://sycamore-rs.netlify.app/docs/advanced/js_interopweekly0.5 https://sycamore-rs.netlify.app/docs/advanced/noderefweekly0.5 +https://sycamore-rs.netlify.app/docs/advanced/optimize_wasm_sizeweekly0.5 https://sycamore-rs.netlify.app/docs/advanced/routingweekly0.5 https://sycamore-rs.netlify.app/docs/advanced/ssrweekly0.5 https://sycamore-rs.netlify.app/docs/advanced/testingweekly0.5 @@ -23,8 +25,6 @@ https://sycamore-rs.netlify.app/docs/getting_started/faqweekly0.5 https://sycamore-rs.netlify.app/docs/getting_started/hello_worldweekly0.5 https://sycamore-rs.netlify.app/docs/getting_started/installationweekly0.5 -https://sycamore-rs.netlify.app/docs/optimizations/code_sizeweekly0.5 -https://sycamore-rs.netlify.app/docs/optimizations/speedweekly0.5 https://sycamore-rs.netlify.app/docs/sidebarweekly0.5 https://sycamore-rs.netlify.app/docs/v0.5/advanced/advanced_reactivityyearly0.3 https://sycamore-rs.netlify.app/docs/v0.5/advanced/cssyearly0.3