Skip to content

Commit

Permalink
New docs for Sycamore v0.9 (#729)
Browse files Browse the repository at this point in the history
* Update CONTRIBUTING.md

* Add a .prettierrc.toml for docs

* Prettier + typo

* Your first app

* Update

* Your first app

* Completed your-first-app.md

* Adding state

* Finished adding-state.md

* Finish todo app tutorial

* wip

* View docs

* Add a bunch of other docs

* Add some stubs for new doc pages

* Add some more stubs

* Fix embarassing typo

* Update links in FAQ
  • Loading branch information
lukechu10 authored Oct 20, 2024
1 parent 24bf5eb commit 4a91338
Show file tree
Hide file tree
Showing 55 changed files with 2,651 additions and 1,621 deletions.
39 changes: 10 additions & 29 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

First, thank you for wanting to contribute! Sycamore is completely free and open-source and could not be so without the help of contributors like you!

Check out our community's [Code of Conduct](https://github.com/sycamore-rs/sycamore/blob/main/CODE_OF_CONDUCT.md) and feel free to say hello on our [Discord server](https://discord.gg/vDwFUmm6mU) if you like. We have a special channel dedicated to Sycamore development where you can ask questions and guidance as well as geting to know other users and contributors of Sycamore in an informal setting.
Check out our community's [Code of Conduct](https://github.com/sycamore-rs/sycamore/blob/main/CODE_OF_CONDUCT.md) and feel free to say hello on our [Discord server](https://discord.gg/vDwFUmm6mU) if you like. We have a special channel dedicated to Sycamore development where you can ask questions and guidance as well as getting to know other users and contributors of Sycamore in an informal setting.

The rest of this document will contain:

Expand Down Expand Up @@ -31,8 +31,7 @@ This section will give a brief tour of Sycamore's project structure and where to
- Integration tests are in `packages/sycamore/tests`.
- Benchmarks are in `packages/tools/bench`.
- Examples are in `examples/`.
- The Sycamore website is in `website/`. This will eventually be moved out into a new repository.
- The documentation is in `docs/`. This also contains a tool for pre-rendering the markdown files into HTML. This will likely be moved into the new website repository when its ready.
- The Sycamore website is developed at [sycamore-rs/website](https://github.com/sycamore-rs/website). Every time `docs/` is modified, a workflow is triggered that will automatically update the website with the latest docs.

### Crates

Expand All @@ -42,16 +41,10 @@ This is the main crate which is intended to be added to the `Cargo.toml` of a Sy

For now, this crate also includes:

- The Builder API. We cannot move this out yet because of inter-dependence with other features.
- Some web-related utilities such as `NoSsr` and `NoHydrate` as well as all the HTML element declarations.
- Easing functions. This should be moved into another crate.
- Flow-control components: `Keyed` and `Indexed`. This is because the proc-macros rely on the `sycamore` crate being at the root.
- `create_resource`. This should probably be moved into the `sycamore-futures` crate.
- Utilities for tweened signals. This should be moved into another crate along with the easing functions.
- Suspense. This is for the same reason as the flow-control components.
- Some utilities used by the codegen of various proc-macros.
- Easing functions for animations.
- Utilities for using the `renderAnimationFrame` API.

The goal is to eventually move most of these into their own crates.
These will eventually be moved into a different crate.

#### `sycamore-macro`

Expand All @@ -67,23 +60,19 @@ The API is mostly inspired by [SolidJS](https://www.solidjs.com/). Behind-the-sc

Everything created inside the reactivity system is owned by the top-level `Root` struct. This includes the node arena as well as global state used for tracking dependencies in memos/effects. Finally, the `Root` is also responsible for propagating updates through the reactive graph.

[This article](https://dev.to/ryansolid/a-hands-on-introduction-to-fine-grained-reactivity-3ndf) provides a good introduction to how reactivity is implemented (albeit in JS). The reactive propagation algorithm takes inspiration from [this article](https://dev.to/modderme123/super-charging-fine-grained-reactive-performance-47ph), modified because our reactive system is eager rather than lazy for better predictibility.
[This article](https://dev.to/ryansolid/a-hands-on-introduction-to-fine-grained-reactivity-3ndf) provides a good introduction to how reactivity is implemented (albeit in JS). The reactive propagation algorithm takes inspiration from [this article](https://dev.to/modderme123/super-charging-fine-grained-reactive-performance-47ph), modified because our reactive system is eager rather than lazy for better predictability.

#### `sycamore-core`

This crate contains all the core utilities for Sycamore's rendering logic. This includes:

- Runtime support for components.
- Swappable rendering backends.
- Hydration code. (TODO: this should proabably be moved to `sycamore-web`).
- `NodeRef`s.
- Runtime support for rendering dynamic views and difing fragments.

This crate is backend-agnostic, meaning that there should be no dependence on `web-sys` or `wasm-bindgen`.
This crate is backend-agnostic, meaning that there should be no dependence on `web-sys` or `wasm-bindgen`. Right now, a lot of the core rendering logic is in `sycamore-web`. We probably want to move as much as possible over into `sycamore-core` to make it backend-agnostic.

#### `sycamore-web`

This crate contains all the web specific rendering logic for Sycamore. This includes, notably, `DomNode`, `HydrateNode`, and `SsrNode`.
This crate contains all the web specific rendering logic for Sycamore. This includes, notably, `DomNode`, `HydrateNode`, and `SsrNode`. This also includes other rendering utilities such as `Keyed`, `Indexed`, `Suspense`, `Transition`, and more... These are all web-specific for now but some should be moved over into `sycamore-core`.

#### `sycamore-futures`

Expand Down Expand Up @@ -166,20 +155,12 @@ When adding an example, the following steps should be taken:
1. Add your example to the `examples/` folder. An easy way to create a new example is the clone an existing example and change the name in the appropriate places (folder name and `Cargo.toml`).
2. Add your example to the list of examples in `examples/README.md` along with a small description of what your example demonstrates.

## Working on the website

The website is in the `website/` folder.

We use [TailwindCSS](https://tailwindcss.com/) to style the website. First run `npm install` in the `website/` folder to install TailwindCSS. Then simply run `trunk serve` to start the dev server.

## Writing docs

All the documentation is in the `docs/` folder. As a general rule, you should only ever modify the docs in `docs/next/` and not touch `docs/versioned_docs/`. The documentation in `docs/next/` will be copied over to `docs/versioned_docs/` when there is a new release.

When writing the docs, you can use the `docs` utility crate to generate the markdown files into HTML to be displayed on the website. It is recommended to run in release mode since rendering can take some time. To run the utility, simply use `cargo run --release` in the `docs/` folder.
All the documentation is in the `docs/` folder. This includes the [Sycamore Book](https://sycamore.dev/book/introduction) as well as blog posts.

## Running benchmarks

We have a very basic benchmark setup in `packages/tools/bench`. Simply run `cargo bench` in that folder to run the micro-benchmarks.

We also have an implementaiton for [js-framework-benchmark](https://github.com/krausest/js-framework-benchmark). Runnig this locally, however, is quite a bit more involved. Instead, the simplest way to run this is to add the "performance" label to your PR which will trigger the CI to run the benchmark automatically on every commit and post the result as a comment. Note, however, that the CI can be very noisy and that measurements should be taken with a grain of salt.
We also have an implementation for [js-framework-benchmark](https://github.com/krausest/js-framework-benchmark). Running this locally, however, is quite a bit more involved. Instead, the simplest way to run this is to add the "performance" label to your PR which will trigger the CI to run the benchmark automatically on every commit and post the result as a comment. Note, however, that the CI can be very noisy and that measurements should be taken with a grain of salt.
1 change: 1 addition & 0 deletions docs/.prettierrc.toml
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
proseWrap = "always"
46 changes: 0 additions & 46 deletions docs/next/advanced/advanced_reactivity.md

This file was deleted.

59 changes: 0 additions & 59 deletions docs/next/advanced/attributes_prop.md

This file was deleted.

71 changes: 0 additions & 71 deletions docs/next/advanced/contexts.md

This file was deleted.

9 changes: 0 additions & 9 deletions docs/next/advanced/js_interop.md

This file was deleted.

26 changes: 0 additions & 26 deletions docs/next/advanced/noderef.md

This file was deleted.

40 changes: 0 additions & 40 deletions docs/next/advanced/ssr.md

This file was deleted.

26 changes: 0 additions & 26 deletions docs/next/advanced/styling.md

This file was deleted.

Loading

0 comments on commit 4a91338

Please sign in to comment.