From 3fe6121c3ced3aae1525bd65525257a7010f4e81 Mon Sep 17 00:00:00 2001 From: Teymour Aldridge <42674621+teymour-aldridge@users.noreply.github.com> Date: Fri, 10 Jul 2020 04:18:21 +0100 Subject: [PATCH] Ci for documentation (#1393) * Add contributing guidelines. * Add spellchecking. * Update dictionary. * Update dictionary. * Update dictionary. --- .github/workflows/doctests.yml | 16 +++ ci/dictionary.txt | 88 +++++++++++++++ ci/spellcheck.sh | 101 ++++++++++++++++++ docs/README.md | 39 +++++++ docs/advanced-topics/optimizations.md | 8 +- docs/concepts/agents.md | 2 +- docs/more/testing.md | 2 +- .../zh-TW/advanced-topics/optimizations.md | 2 +- 8 files changed, 251 insertions(+), 7 deletions(-) create mode 100644 .github/workflows/doctests.yml create mode 100644 ci/dictionary.txt create mode 100755 ci/spellcheck.sh create mode 100644 docs/README.md diff --git a/.github/workflows/doctests.yml b/.github/workflows/doctests.yml new file mode 100644 index 000000000..021563514 --- /dev/null +++ b/.github/workflows/doctests.yml @@ -0,0 +1,16 @@ +name: Documentation tests +on: + push: + paths: + - "docs/**/*" + pull_request: + paths: + - "docs/**/*" + +jobs: + check-spelling: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v2 + - name: Check spelling + run: bash ci/spellcheck.sh list diff --git a/ci/dictionary.txt b/ci/dictionary.txt new file mode 100644 index 000000000..125c5b18c --- /dev/null +++ b/ci/dictionary.txt @@ -0,0 +1,88 @@ +personal_ws-1.1 en 72 utf-8 +APIs +AddOne +Angular's +Borrow +BorrowMut +ComponentLink +Config +ConsoleService +DevTools +Deref +DerefMut +ExampleProps +Github +HashMap +Lifecycle +MaterialUi +NeqAssign +Optimisations +Optimizations +PartialEq +PureComponents +README +RouteAgent +RouteService +Routeservice +ShouldRender +SomePureComponent +TODO +Todo +WebAssembly +Webpack +Workspaces +alloc +allocator +asmjs +backends +behavior +binaryen +bincode +bindgen +boolean +cdylib +codebase +codegen +emscripten +endcode +enum +enums +favor +html +impl +init +interoperability +interoperable +INIT +libs +lifecycle +memoized +minimising +minimize +natively +optimization +optimizations +optimize +optimizes +proc +roadmap +rollup +rustwasm +serializing +stacktraces +standardization +stdweb +struct +structs +thead +tbody +toml +TryFrom +unboxed +usize +vdom +Vec +VecDeque +wasm +WeeAlloc +yewtil diff --git a/ci/spellcheck.sh b/ci/spellcheck.sh new file mode 100755 index 000000000..1a38712e0 --- /dev/null +++ b/ci/spellcheck.sh @@ -0,0 +1,101 @@ +#!/bin/bash + +aspell --version + +# Taken from the Rust Book (https://github.com/rust-lang/book/) + +# Checks project Markdown files for spelling mistakes. + +# Notes: + +# This script needs dictionary file ($dict_filename) with project-specific +# valid words. If this file is missing, first invocation of a script generates +# a file of words considered typos at the moment. User should remove real typos +# from this file and leave only valid words. When script generates false +# positive after source modification, new valid word should be added +# to dictionary file. + +# Default mode of this script is interactive. Each source file is scanned for +# typos. aspell opens window, suggesting fixes for each found typo. Original +# files with errors will be backed up to files with format "filename.md.bak". + +# When running in CI, this script should be run in "list" mode (pass "list" +# as first argument). In this mode script scans all files and reports found +# errors. Exit code in this case depends on scan result: +# 1 if any errors found, +# 0 if all is clear. + +# Script skips words with length less than or equal to 3. This helps to avoid +# some false positives. + +# We can consider skipping source code in markdown files (```code```) to reduce +# rate of false positives, but then we lose ability to detect typos in code +# comments/strings etc. + +shopt -s nullglob + +dict_filename=./ci/dictionary.txt +markdown_sources=(./docs/**/*.md) +mode="check" + +# aspell repeatedly modifies the personal dictionary for some reason, +# so we should use a copy of our dictionary. +dict_path="/tmp/dictionary.txt" + +if [[ "$1" == "list" ]]; then + mode="list" +fi + +# Error if running in list (CI) mode and there isn't a dictionary file; +# creating one in CI won't do any good :( +if [[ "$mode" == "list" && ! -f "$dict_filename" ]]; then + echo "No dictionary file found! A dictionary file is required in CI!" + exit 1 +fi + +if [[ ! -f "$dict_filename" ]]; then + # Pre-check mode: generates dictionary of words aspell consider typos. + # After user validates that this file contains only valid words, we can + # look for typos using this dictionary and some default aspell dictionary. + echo "Scanning files to generate dictionary file '$dict_filename'." + echo "Please check that it doesn't contain any misspellings." + + echo "personal_ws-1.1 en 0 utf-8" > "$dict_filename" + cat "${markdown_sources[@]}" | aspell --ignore 3 list | sort -u >> "$dict_filename" +elif [[ "$mode" == "list" ]]; then + # List (default) mode: scan all files, report errors. + declare -i retval=0 + + cp "$dict_filename" "$dict_path" + + if [ ! -f $dict_path ]; then + retval=1 + exit "$retval" + fi + + for fname in "${markdown_sources[@]}"; do + command=$(aspell --ignore 3 --personal="$dict_path" "$mode" < "$fname") + if [[ -n "$command" ]]; then + for error in $command; do + # FIXME: find more correct way to get line number + # (ideally from aspell). Now it can make some false positives, + # because it is just a grep. + grep --with-filename --line-number --color=always "$error" "$fname" + done + retval=1 + fi + done + exit "$retval" +elif [[ "$mode" == "check" ]]; then + # Interactive mode: fix typos. + cp "$dict_filename" "$dict_path" + + if [ ! -f $dict_path ]; then + retval=1 + exit "$retval" + fi + + for fname in "${markdown_sources[@]}"; do + aspell --ignore 3 --dont-backup --personal="$dict_path" "$mode" "$fname" + done +fi diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 000000000..d3410ba16 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,39 @@ +# Contributing to the documentation + +Firstly, thanks for considering contributing to Yew. We're a friendly community of humans who +collaborate to build (hopefully) awesome software. We try to write software which is easy to use so +we ask that you follow a few guidelines when contributing – these are laid out in this document. + +Note that this document is about *contributing documentation* not contributing code and only +applies to the contents of the `docs` folder – not any other parts of the project. + +## Can I just submit a PR or do I need to create an issue first? + +PRs not attached to previously created issues are welcome *if* they're a small change. This could +be something like fixing a small grammar mistake or a typo. + +If your PR is something bigger create an issue beforehand. This will save everyone time and effort: + +1. Multiple people don't end up submitting duplicate PRs doing the same thing. +2. People have a chance to submit feedback on an idea *before* someone does a lot of work on it. +3. It's easy to track progress on the development of the documentation. + +## Spelling and grammar + +We recognise that not everyone who contributes to Yew will have "perfect" grammar or be a native +English speaker. We're all human; everyone makes mistakes and nobody will look down on you if you +make typos or grammar mistakes (we'll just fix them, merge PRs and move on with life). + +To help catch spelling mistakes, we use a spellchecking script which originally came from the Rust +Book. If it picks up a spelling "mistake" which isn't actually a mistake, then please add it to the +list in `ci/dictionary.txt` (in alphabetically sorted order). + +If in doubt about spelling, grammar or style you might find it useful to consult the +[Microsoft Style Guide](https://docs.microsoft.com/style-guide/) which we sometimes use as a handy +reference. + +## Line wrap +Having really long lines makes it hard to review code and see differences between versions. To +solve this problem all lines should be wrapped at 100 characters. + +If you're editing a line which is more than 100 characters long, please feel free to shorten it! \ No newline at end of file diff --git a/docs/advanced-topics/optimizations.md b/docs/advanced-topics/optimizations.md index d70d618bb..e1ac1f30e 100644 --- a/docs/advanced-topics/optimizations.md +++ b/docs/advanced-topics/optimizations.md @@ -58,7 +58,7 @@ Function components don't exist yet, but in theory, pure components could be gen ## Compile speed optimizations using Cargo Workspaces -Arguabley, the largest drawback to using Yew is the long time it takes to compile. Compile time seems to correlate with the quantity of code found within `html!` macro blocks. This tends to not be a significant problem for smaller projects, but for webapps that span multiple pages, it makes sense to break apart your code across multiple crates to minimize the amount of work the compiler has to do. +Arguably, the largest drawback to using Yew is the long time it takes to compile. Compile time seems to correlate with the quantity of code found within `html!` macro blocks. This tends to not be a significant problem for smaller projects, but for web apps that span multiple pages, it makes sense to break apart your code across multiple crates to minimize the amount of work the compiler has to do. You should try to make your main crate handle routing/page selection, move all commonly shared code to another crate, and then make a different crate for each page, where each page could be a different component, or just a big function that produces `Html`. In the best case scenario, you go from rebuilding all of your code on each compile to rebuilding only the main crate, and one of your page crates. In the worst case, where you edit something in the "common" crate, you will be right back to where you started: compiling all code that depends on that commonly shared crate, which is probably everything else. @@ -67,7 +67,7 @@ If your main crate is too heavyweight, or you want to rapidly iterate on a deepl ## Build size optimization * optimize Rust code - * `wee_aloc` \( using tiny allocator \) + * `wee_alloc` \( using tiny allocator \) * `cargo.toml` \( defining release profile \) * optimize wasm code using `wasm-opt` @@ -97,7 +97,7 @@ It is possible to setup release build for smaller size using `[profile.release]` panic = 'abort' # optimization over all codebase ( better optimization, slower build ) codegen-units = 1 -# optimization for size ( more aggresive ) +# optimization for size ( more aggressive ) opt-level = 'z' # optimization for size # opt-level = 's' @@ -127,6 +127,6 @@ Note: `wasm-pack` combines optimization for Rust and wasm code. `wasm-bindgen` i | used tool | size | | :--- | :--- | | wasm-bindgen | 158KB | -| wasm-binggen + wasm-opt -Os | 116KB | +| wasm-bindgen + wasm-opt -Os | 116KB | | wasm-pack | 99 KB | diff --git a/docs/concepts/agents.md b/docs/concepts/agents.md index 5b4349cce..6ac039543 100644 --- a/docs/concepts/agents.md +++ b/docs/concepts/agents.md @@ -4,7 +4,7 @@ description: Yew's Actor System # Agents -Agents are similar to Angular's [Services](https://angular.io/guide/architecture-services) \(but without dependency injection\), and provide a Yew with an [Actor Model](https://en.wikipedia.org/wiki/Actor_model). Agents can be used to route messages between components independently of where they sit in the component hierarchy, or they can be used to create a global state, and they can also be used to offload computationally expensive tasks from the main thread which renders the UI. There is also planned support for using agents to allow Yew applications to communicate accross tabs \(in the future\). +Agents are similar to Angular's [Services](https://angular.io/guide/architecture-services) \(but without dependency injection\), and provide a Yew with an [Actor Model](https://en.wikipedia.org/wiki/Actor_model). Agents can be used to route messages between components independently of where they sit in the component hierarchy, or they can be used to create a global state, and they can also be used to offload computationally expensive tasks from the main thread which renders the UI. There is also planned support for using agents to allow Yew applications to communicate across tabs \(in the future\). In order for agents to run concurrently, Yew uses [web-workers](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Using_web_workers). diff --git a/docs/more/testing.md b/docs/more/testing.md index 70be809a5..2f9420d2a 100644 --- a/docs/more/testing.md +++ b/docs/more/testing.md @@ -6,7 +6,7 @@ description: Testing your app <TODO> -## wasm\_bingen\_test +## wasm\_bindgen\_test The Rust WASM working group maintains a crate called [`wasm_bindgen_test`](https://rustwasm.github.io/docs/wasm-bindgen/wasm-bindgen-test/index.html) which allows you to run tests in a browser in similar fashion to how the built-in `#[test]` procedural macro works. More information is given in the [Rust WASM working group's documentation](https://rustwasm.github.io/docs/wasm-bindgen/wasm-bindgen-test/index.html) for this module. diff --git a/website/translated_docs/zh-TW/advanced-topics/optimizations.md b/website/translated_docs/zh-TW/advanced-topics/optimizations.md index e754faeb1..74b2d954f 100644 --- a/website/translated_docs/zh-TW/advanced-topics/optimizations.md +++ b/website/translated_docs/zh-TW/advanced-topics/optimizations.md @@ -67,7 +67,7 @@ Yew 最大的缺點就是花太多時間在編譯上了。編譯時間似乎和 ## 編譯大小的優化 * 優化 Rust 的程式碼 - * `wee_aloc` （使用輕量的分配器） + * `wee_alloc` （使用輕量的分配器） * `cargo.toml` （定義釋出的設定檔） * 使用 `wasm-opt` 優化 wasm 程式碼