From cf89855cbac3c6d67b1f4f884443d0b7c189df1b Mon Sep 17 00:00:00 2001 From: Leonard Date: Wed, 30 Aug 2023 21:57:29 +0200 Subject: [PATCH] Add files from https://github.com/DioxusLabs/dioxus/pull/1404 Additional changes: * More English fixes. * Removed plugin docs from SUMMARY.md, since they are not going to be using Lua. However, I left the folder there for future reference. * Removed governance.md from SUMMARY.md, because it doesn't contain anything. --- .gitignore | 2 + README.md | 1 - docs-src/0.4/SUMMARY.md | 11 +- docs-src/0.4/en/CLI/cmd/build.md | 47 --- docs-src/0.4/en/CLI/cmd/bundle.md | 67 ----- docs-src/0.4/en/CLI/cmd/clean.md | 18 -- docs-src/0.4/en/CLI/cmd/index.md | 27 -- docs-src/0.4/en/CLI/cmd/serve.md | 61 ---- docs-src/0.4/en/CLI/cmd/translate.md | 68 ----- docs-src/0.4/en/CLI/configure.md | 283 +++++++----------- docs-src/0.4/en/CLI/creating.md | 36 +-- docs-src/0.4/en/CLI/index.md | 24 +- docs-src/0.4/en/CLI/installation.md | 25 +- docs-src/0.4/en/CLI/plugin/index.md | 88 +++++- .../0.4/en/CLI/plugin/interface/command.md | 10 +- docs-src/0.4/en/CLI/plugin/interface/dirs.md | 19 +- docs-src/0.4/en/CLI/plugin/interface/log.md | 22 +- .../0.4/en/CLI/plugin/interface/network.md | 15 +- docs-src/0.4/en/CLI/plugin/interface/os.md | 6 +- docs-src/0.4/en/CLI/plugin/interface/path.md | 25 +- .../{governence.md => governance.md} | 0 21 files changed, 268 insertions(+), 587 deletions(-) delete mode 100644 docs-src/0.4/en/CLI/cmd/build.md delete mode 100644 docs-src/0.4/en/CLI/cmd/bundle.md delete mode 100644 docs-src/0.4/en/CLI/cmd/clean.md delete mode 100644 docs-src/0.4/en/CLI/cmd/index.md delete mode 100644 docs-src/0.4/en/CLI/cmd/serve.md delete mode 100644 docs-src/0.4/en/CLI/cmd/translate.md rename docs-src/0.4/en/contributing/{governence.md => governance.md} (100%) diff --git a/.gitignore b/.gitignore index 759a0c6a1..068a60f39 100644 --- a/.gitignore +++ b/.gitignore @@ -8,6 +8,8 @@ Cargo.lock !.vscode/launch.json !.vscode/extensions.json +.idea + /pkg /static /docs/learn/0.3 diff --git a/README.md b/README.md index ecfa3c47f..550463879 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,6 @@ Run the following command in the root of the project to start the tailwind css c npx tailwindcss -i ./input.css -o ./public/tailwind.css --watch ``` - The documentation can be edited using any text editor. Most commonly used editors support syntax highlighting for the `markdown` format. To view your changes you can install the [dioxus-cli] tool locally, assuming you already have a working `Rust` setup; ```console cargo install dioxus-cli diff --git a/docs-src/0.4/SUMMARY.md b/docs-src/0.4/SUMMARY.md index ad65d6962..edbbc789c 100644 --- a/docs-src/0.4/SUMMARY.md +++ b/docs-src/0.4/SUMMARY.md @@ -81,18 +81,15 @@ - [Installation](CLI/installation.md) - [Create a Project](CLI/creating.md) - [Configure Project](CLI/configure.md) - - [Commands](CLI/cmd/index.md) - - [Build](CLI/cmd/build.md) - - [Serve](CLI/cmd/serve.md) - - [Clean](CLI/cmd/clean.md) - - [Translate](CLI/cmd/translate.md) - - [Plugin Development](CLI/plugin/index.md) + --- - [Contributing](contributing/index.md) @@ -100,7 +97,7 @@ - [Walkthrough of Internals](contributing/walkthrough_readme.md) - [Guiding Principles](contributing/guiding_principles.md) - [Roadmap](contributing/roadmap.md) - - [Governence](contributing/governence.md) + --- - [Migration](migration/index.md) diff --git a/docs-src/0.4/en/CLI/cmd/build.md b/docs-src/0.4/en/CLI/cmd/build.md deleted file mode 100644 index c447933b5..000000000 --- a/docs-src/0.4/en/CLI/cmd/build.md +++ /dev/null @@ -1,47 +0,0 @@ -# Build - -The `dx build` command can help you `pack & build` a dioxus project. - -``` -dioxus-build -Build the Rust WASM app and all of its assets - -USAGE: - dx build [OPTIONS] - -OPTIONS: - --example [default: ""] - --platform [default: "default_platform"] - --release [default: false] -``` - -You can use this command to build a project: - -``` -dx build --release -``` - -## Target platform - -Use the `platform` option to choose your target platform: - -``` -# for desktop project -dx build --platform desktop -``` - -`platform` currently only supports `desktop` & `web`. - -``` -# for web project -dx build --platform web -``` - -## Build Example - -You can use the `example` option to select a example to build: - -``` -# build the `test` example -dx build --example test -``` \ No newline at end of file diff --git a/docs-src/0.4/en/CLI/cmd/bundle.md b/docs-src/0.4/en/CLI/cmd/bundle.md deleted file mode 100644 index 63c99b3d9..000000000 --- a/docs-src/0.4/en/CLI/cmd/bundle.md +++ /dev/null @@ -1,67 +0,0 @@ -# Bundle - -The `dioxus bundle` command can help you bundle a dioxus project. - -``` -dioxus-bundle -Bundle the Rust desktop app and all of its assets - -USAGE: - dioxus bundle [OPTIONS] - -OPTIONS: - --example [default: ""] - --platform [default: "default_platform"] - --release [default: false] - --package [default: platform specific] -``` - -You can use this command to create an installer for a project in the `out_dir`: - -``` -dioxus bundle --release -``` - -## Target Platform - -Use option `platform` choose build target platform: - -``` -# for desktop project -dioxus bundle --platform desktop -``` - -`platform` only supports `desktop` & `web`. - -``` -# for web project -dioxus bundle --platform web -``` - -## Bundle Example - -You can use `--example {name}` to build a example code. - -``` -# bundle the `example/test` -dioxus bundle --exmaple test -``` - -## Target Package - -Depending on the target platform, the following packages are available: -Windows: -`msi`: (.msi) -Macos: -`macos`: (.app) -`ios`: IOS app bundle -`dmg`: macOS DMG bundle (.dmg) -Linux: -`deb`: Debian package bundle (.deb) -`rpm`: RPM package bundle (.rpm) -`appimage`: AppImage bundle (.AppImage) - -``` -# bundle a msi package for windows -dioxus bundle --package msi -``` diff --git a/docs-src/0.4/en/CLI/cmd/clean.md b/docs-src/0.4/en/CLI/cmd/clean.md deleted file mode 100644 index dc8c0ca11..000000000 --- a/docs-src/0.4/en/CLI/cmd/clean.md +++ /dev/null @@ -1,18 +0,0 @@ -# Clean - -`dx clean` will clear the build artifacts (the out_dir and the cargo cache) - -``` -dioxus-clean -Clean build artifacts - -USAGE: - dx clean -``` - -# Example - -``` -dx clean -``` - diff --git a/docs-src/0.4/en/CLI/cmd/index.md b/docs-src/0.4/en/CLI/cmd/index.md deleted file mode 100644 index ea4c1c723..000000000 --- a/docs-src/0.4/en/CLI/cmd/index.md +++ /dev/null @@ -1,27 +0,0 @@ -# Commands - -In this chapter we will introduce all `dioxus-cli` commands. - -> You can also use `dioxus --help` to get cli help info. - -``` -dioxus -Build, bundle, & ship your Dioxus app - -USAGE: - dioxus [OPTIONS] - -OPTIONS: - -h, --help Print help information - -v Enable verbose logging - -SUBCOMMANDS: - bundle Bundle the Rust desktop app and all of its assets - build Build the Dioxus application and all of its assets - clean Clean output artifacts - config Dioxus config file controls - create Init a new project for Dioxus - help Print this message or the help of the given subcommand(s) - serve Build, watch & serve the Rust WASM app and all of its assets - translate Translate some html file into a Dioxus component -``` \ No newline at end of file diff --git a/docs-src/0.4/en/CLI/cmd/serve.md b/docs-src/0.4/en/CLI/cmd/serve.md deleted file mode 100644 index 2c5384de0..000000000 --- a/docs-src/0.4/en/CLI/cmd/serve.md +++ /dev/null @@ -1,61 +0,0 @@ -# Serve - -The `dx serve` can start a dev server with hot-reloading - -``` -dioxus-serve -Build, watch & serve the Rust WASM app and all of its assets - -USAGE: - dx serve [OPTIONS] - -OPTIONS: - --example [default: ""] - --platform [default: "default_platform"] - --release [default: false] - --hot-reload [default: false]ß -``` - -You can use this command to build project and start a dev server: - -``` -dx serve -``` - -## Serve Example - -You can use the `example` option to serve a example: - -``` -# serve the `test` example -dx serve --example test -``` - -## Open Browser - -You can add the `--open` option to open system default browser when server startup: - -``` -dx serve --open -``` - -## RSX Hot Reloading - -You can add the `--hot-reload` flag to enable rsx hot reloading. This will allow you to reload some rsx changes without a full recompile: - -``` -dx serve --open -``` - -## Cross Origin Policy - -You can add the `cross-origin-policy` option to change cross-origin header to: - -``` - Cross-Origin-Opener-Policy: same-origin - Cross-Origin-Embedder-Policy: require-corp -``` - -``` -dx serve --corss-origin-policy -``` \ No newline at end of file diff --git a/docs-src/0.4/en/CLI/cmd/translate.md b/docs-src/0.4/en/CLI/cmd/translate.md deleted file mode 100644 index 7895a2916..000000000 --- a/docs-src/0.4/en/CLI/cmd/translate.md +++ /dev/null @@ -1,68 +0,0 @@ -# Translate - -`dioxus translate` can translate some `html` file into a Dioxus component - -``` -dioxus-translate -Translate some source file into a Dioxus component - -USAGE: - dioxus translate [OPTIONS] [OUTPUT] - -ARGS: - Output file, defaults to stdout if not present - -OPTIONS: - -c, --component Activate debug mode - -f, --file Input file -``` - -## Translate HTML to stdout - -You can use the `file` option to set path to the `html` file to translate: - -``` -dioxus transtale --file ./index.html -``` - -## Output rsx to a file - -You can pass a file to the translate command to set the path to write the output of the command to: - -``` -dioxus translate --file ./index.html component.rsx -``` - -## Output rsx to a file - -Setting the `component` option will create a component from the HTML: - -``` -dioxus translate --file ./index.html --component -``` - -## Example - -This HTML: -```html -
-

Hello World

- Link -
-``` - -Translates into this Dioxus component: - -```rust -fn component(cx: Scope) -> Element { - cx.render(rsx! { - div { - h1 { "Hello World" }, - a { - href: "https://dioxuslabs.com/", - "Link" - } - } - }) -} -``` \ No newline at end of file diff --git a/docs-src/0.4/en/CLI/configure.md b/docs-src/0.4/en/CLI/configure.md index 586edee1a..bb4911a45 100644 --- a/docs-src/0.4/en/CLI/configure.md +++ b/docs-src/0.4/en/CLI/configure.md @@ -1,219 +1,176 @@ # Configure Project -This chapter will introduce `Dioxus.toml` and anatomy the config file. +This chapter will teach you how to configure the CLI with the `Dioxus.toml` file. +There's an [example](#config-example) which has comments to describe individual keys. +You can copy that or view this documentation for a more complete learning experience. -## Structure +"🔒" indicates a mandatory item. +Some headers are mandatory, but none of the keys inside them are. +In that case, you only need to include the header, but no keys. +It might look weird, but it's normal. -We use `toml` to define some info for `dioxus` project. +## Structure -### Application +Each header has its TOML form directly under it. -1. **_name_** - project name & title -2. **_default_platform_** - which platform target for this project. - ``` - # current support: web, desktop - # default: web - default_platform = "web" - ``` - change this to `desktop`, the `dx build & serve` will default build desktop app. -3. **_out_dir_** - which directory to put the output file; use `dx build & service`, the output will put at this directory, and the `assets` will be also copy to here. - ``` - out_dir = "dist" - ``` -4. **_asset_dir_** - which direcotry to put your `static, assets` file, cli will automatic copy all file to `out_dir`, so you can put some resource file in there, like `CSS, JS, Image` file. - ``` - asset_dir = "public" - ``` +### Application 🔒 -### Application.Tools +```toml +[application] +``` -You can combine different tools with `dioxus`. +Application-wide configuration. Applies to both web and desktop. -1. **_binaryen_** - Use the `binaryen` tooling suite. +* **name** 🔒 - Project name & title. + ```toml + name = "my_project" ``` - # current support: wasm-opt - # default: web - binaryen = { wasm_opt = true } +* **default_platform** 🔒 - The platform this project targets + ```toml + # Currently supported platforms: web, desktop + default_platform = "web" ``` - Use the `wasm_opt = true` key/pair value to activate optimization with wasm-opt. - When building on `release` profile, Dioxus will run `wasm_opt` with `-Oz` option. -2. **_tailwindcss_** - Use the `tailwindcss` standalone binary to generate a Tailwind CSS bundle file. - +* **out_dir** - The directory to place the build artifacts from `dx build` or `dx serve` into. This is also where the `assets` directory will be copied into. + ```toml + out_dir = "dist" + ``` +* **asset_dir** - The directory with your static assets. The CLI will automatically copy these assets into the **out_dir** after a build/serve. + ```toml + asset_dir = "public" ``` - tailwindcss = { input = "main.css", config = "tailwind.config.js" } +* **sub_package** - The sub package in the workspace to build by default. + ```toml + sub_package = "my-crate" ``` - You can set two optional keys : - - - input: path of the input CSS file (default value is "public/tailwind.css") - - config: path to the config file for Tailwind (default value is "src/tailwind.config.js") - - When building on `release` profile, Dioxus will run `tailwindcss` with the `--minify` option. +### Web.App 🔒 - Note : Dioxus will automatically include the generated tailwind file in the `index.html` - -### Web.App +```toml +[web.app] +``` -Web platform application config: +Web-specific configuration. -1. **_title_** - this value will display on the web page title. like `` tag. - ``` +* **title** - The title of the web page. + ```toml # HTML title tag content - title = "dioxus app | ⛺" + title = "project_name" + ``` +* **base_path** - The base path to build the application for serving at. This can be useful when serving your application in a subdirectory under a domain. For example, when building a site to be served on GitHub Pages. + ```toml + # The application will be served at domain.com/my_application/, so we need to modify the base_path to the path where the application will be served + base_path = "my_application" ``` -### Web.Watcher +### Web.Watcher ✍ -Web platform `dev-server` watcher config: +```toml +[web.watcher] +``` -1. **_reload_html_** - a boolean value; when watcher trigger, regenerate `index.html` file. - ``` - # when watcher trigger, regenerate the `index.html` +Development server configuration. + +* **reload_html** - If this is true, the cli will rebuild the index.html file every time the application is rebuilt + ```toml reload_html = true ``` -2. **_watch_path_** - which files & directories will be watcher monitoring. - ``` +* **watch_path** - The files & directories to monitor for changes + ```toml watch_path = ["src", "public"] ``` -### Web.Resource - -Include some `CSS Javascript` resources into html file. - -1. **_style_** - include some style(CSS) file into html. - ``` - style = [ - # include from public_dir. - "./assets/style.css", - # or some asset from online cdn. - "https://cdn.jsdelivr.net/npm/bootstrap/dist/css/bootstrap.css" - ] - ``` -2. **_script_** - include some script(JS) file into html. - ``` - style = [ - # include from public_dir. - "./assets/index.js", - # or some asset from online cdn. - "https://cdn.jsdelivr.net/npm/bootstrap/dist/js/bootstrap.js" - ] +* **index_on_404** - If enabled, Dioxus will serve the root page when a route is not found. + *This is needed when serving an application that uses the router*. + However, when serving your app using something else than Dioxus (e.g. GitHub Pages), you will have to check how to configure it on that platform. + In GitHub Pages, you can make a copy of `index.html` named `404.html` in the same directory. + ```toml + index_on_404 = true ``` -### Web.Resource.Dev +### Web.Resource 🔒 + +```toml +[web.resource] +``` -Only include resources at `Dev` mode. +Static resource configuration. -1. **_style_** - include some style(CSS) file into html. - ``` +* **style** - CSS files to include in your application. + ```toml style = [ - # include from public_dir. + # Include from public_dir. "./assets/style.css", - # or some asset from online cdn. + # Or some asset from online cdn. "https://cdn.jsdelivr.net/npm/bootstrap/dist/css/bootstrap.css" ] ``` -2. **_script_** - include some script(JS) file into html. - ``` - script = [ - # include from public_dir. - "./assets/index.js", - # or some asset from online cdn. - "https://cdn.jsdelivr.net/npm/bootstrap/dist/js/bootstrap.js" - ] - ``` - -### Web.Proxy - -Proxy requests matching a path to a backend server. - -1. **_backend_** - the URL to the backend server. - ``` - backend = "http://localhost:8000/api/" - ``` - This will cause any requests made to the dev server with prefix /api/ to be redirected to the backend server at http://localhost:8000. The path and query parameters will be passed on as-is (path rewriting is not currently supported). - -### Bundle - -Information to include in the bundled output. - -1. **_identifier_** - a string value; the identifier of the bundle. - ``` - identifier = "com.dioxus.app" - ``` -2. **_publisher_** - a string value; the publisher of the bundle. - ``` - publisher = "dioxus" - ``` -3. **_icon_** - a list of strings; the icons for the bundle. - - ``` - icon = ["assets/icon.png"] - ``` -4. **_resources_** - a list of glob patterns; resources to include in the bundle. - - ``` - resources = ["assets/*"] +* **script** - JavaScript files to include in your application. + ```toml + script = [ + # Include from asset_dir. + "./public/index.js", + # Or from an online CDN. + "https://cdn.jsdelivr.net/npm/bootstrap/dist/js/bootstrap.js" + ] ``` -5. **_copyright_** - a string value; the copyright of the bundle. - - ``` - copyright = "Copyright (c) Jane Doe 2016. All rights reserved." - ``` +### Web.Resource.Dev 🔒 -6. **_category_** - a string value; the category of the bundle. one of these values: `Business`, `Developer Tool`, `Education`, `Entertainment`, `Finance`, `Game`, `Action Game`, `Adventure Game`, `Arcade Game`, `Board Game`, `Card Game`, `Casino Game`, `Dice Game`, `Educational Game`, `Family Game`, `Kids Game`, `Music Game`, `Puzzle Game`, `Racing Game`, `Role-Playing Game`, `Simulation Game`, `Sports Game`, `Strategy Game`, `Trivia Game`, `Word Game`, `Graphics and Design`, `Healthcare and Fitness`, `Lifestyle`, `Medical`, `Music`, `News`, `Photography`, `Productivity`, `Reference`, `Social Networking`, `Sports`, `Travel`, `Utility`, `Video`, `Weather`, +```toml +[web.resource.dev] +``` - ``` - category = "Business" - ``` +This is the same as [`[web.resource]`](#webresource-), but it only works in development servers. +For example, if you want to include a file in a `dx serve` server, but not a `dx serve --release` server, put it here. -7. **_short_description_** - a string value; the short description of the bundle. +### Web.Proxy - ``` - short_description = "A short description of the bundle." - ``` +```toml +[[web.proxy]] +``` -8. **_long_description_** - a string value; the long description of the bundle. +Configuration related to any proxies your application requires during development. Proxies will forward requests to a new service. +* **backend** - The URL to the server to proxy. The CLI will forward any requests under the backend relative route to the backend instead of returning 404 + ```toml + backend = "http://localhost:8000/api/" ``` - long_description = """ - A long description of the bundle. - """ - ``` + This will cause any requests made to the dev server with prefix /api/ to be redirected to the backend server at http://localhost:8000. The path and query parameters will be passed on as-is (path rewriting is currently not supported). ## Config example +This includes all fields, mandatory or not. + ```toml [application] -# App (Project) Name -name = "{{project-name}}" +# App name +name = "project_name" -# Dioxus App Default Platform -# desktop, web, mobile, ssr +# The Dioxus platform to default to default_platform = "web" -# `build` & `serve` dist path +# `build` & `serve` output path out_dir = "dist" -# resource (public) file folder +# The static resource path asset_dir = "public" [web.app] # HTML title tag content -title = "dioxus | ⛺" +title = "project_name" [web.watcher] -# when watcher trigger, regenerate the `index.html` +# When watcher is triggered, regenerate the `index.html` reload_html = true -# which files or dirs will be watcher monitoring +# Which files or dirs will be monitored watch_path = ["src", "public"] -# include `assets` in web platform +# Include style or script assets [web.resource] # CSS style file @@ -224,42 +181,14 @@ script = [] [web.resource.dev] -# serve: [dev-server] only +# Same as [web.resource], but for development servers # CSS style file style = [] -# Javascript code file +# JavaScript files script = [] [[web.proxy]] backend = "http://localhost:8000/api/" - -[bundle] - -# Bundle identifier -identifier = "com.dioxus.app" - -# Bundle publisher -publisher = "dioxus" - -# Bundle icon. On windows, the icon file will default to `icons/icon.ico` -icon = ["assets/icon.png"] - -# Bundle resources -resources = ["assets/*"] - -# Bundle copyright -copyright = "Copyright (c) Jane Doe 2016. All rights reserved." - -# Bundle category -category = "Business" - -# Bundle short description -short_description = "A short description of the bundle." - -# Bundle long description -long_description = """ -A long description of the bundle. -""" ``` diff --git a/docs-src/0.4/en/CLI/creating.md b/docs-src/0.4/en/CLI/creating.md index 6c2d5754c..486f8a04b 100644 --- a/docs-src/0.4/en/CLI/creating.md +++ b/docs-src/0.4/en/CLI/creating.md @@ -1,39 +1,25 @@ # Create a Project -Once you have the Dioxus CLI tool installed, you can use it to create dioxus project. +Once you have the Dioxus CLI installed, you can use it to create your own project! -## Initializing a default project +## Initializing a project -First, run the `dx create` command to create a new project ready to be used with Dioxus and the Dioxus CLI: +First, run the `dx create hello-dioxus` command to create a new project. -``` -dx create hello-dioxus -``` - -> It will clone a default template from github template: [DioxusLabs/dioxus-template](https://github.com/DioxusLabs/dioxus-template) -> This default template is use for `web` platform application. +> It clones this [template](https://github.com/DioxusLabs/dioxus-template), which is used for web apps. > -> You can choose to create your project from a different template by passing the `template` argument: +> You can create your project from a different template by passing the `template` argument: > ``` -> dx init hello-dioxus --template=gh:dioxuslabs/dioxus-template +> dx create hello-dioxus --template gh:dioxuslabs/dioxus-template > ``` -Next, move the current directory into your new project: - -``` -cd hello-dioxus -``` +Next, navigate into your new project using `cd hello-dioxus`, or simply opening it in an IDE. -> Make sure `wasm32 target` is installed before running the Web project. -> You can install the wasm target for rust using rustup: +> Make sure the WASM target is installed before running the projects. +> You can install the WASM target for rust using rustup: > ``` > rustup target add wasm32-unknown-unknown > ``` -Finally, create serve your project with the Dioxus CLI: - -``` -dx serve -``` - -By default, the CLI serve your site at: [`http://127.0.0.1:8080/`](http://127.0.0.1:8080/) +Finally, serve your project with `dx serve`! +The CLI will tell you the address it is serving on, along with additional info such as code warnings. \ No newline at end of file diff --git a/docs-src/0.4/en/CLI/index.md b/docs-src/0.4/en/CLI/index.md index 2f857a2a5..5743b1fd6 100644 --- a/docs-src/0.4/en/CLI/index.md +++ b/docs-src/0.4/en/CLI/index.md @@ -1,21 +1,15 @@ # Introduction -📦✨ **Dioxus-Cli** is a tool to help get dioxus projects off the ground. +The ✨**Dioxus CLI**✨ is a tool to get Dioxus projects off the ground. -![dioxus-logo](https://dioxuslabs.com/guide/images/dioxuslogo_full.png) - -It includes `dev server`, `hot reload` and some `quick command` to help you use dioxus. +There's no documentation for commands here, +but you can see all commands using `dx --help` once you've installed the CLI! +Furthermore, you can run `dx --help` to get help with a specific command. ## Features -- [x] `html` to `rsx` conversion tool -- [x] hot reload for `web` platform -- [x] create dioxus project from `git` repo -- [x] build & pack dioxus project -- [ ] autoformat dioxus `rsx` code - -## Contributors - -Contributors to this guide: - -- [mrxiaozhuox](https://github.com/mrxiaozhuox) \ No newline at end of file +* Build and pack a Dioxus project. +* Format `rsx` code. +* Hot Reload for `web` platform. +* Create a Dioxus project from a template repository. +* And more! \ No newline at end of file diff --git a/docs-src/0.4/en/CLI/installation.md b/docs-src/0.4/en/CLI/installation.md index 5957054c1..bb88ecac2 100644 --- a/docs-src/0.4/en/CLI/installation.md +++ b/docs-src/0.4/en/CLI/installation.md @@ -1,22 +1,23 @@ # Installation -Choose any one of the methods below to install the Dioxus CLI: - -## Install from latest git version - -To get the most up to date bug fixes and features of the Dioxus CLI, you can install the development version from git. +## Install the stable version (recommended) ``` -cargo install --git https://github.com/DioxusLabs/dioxus/tree/master/packages/cli +cargo install dioxus-cli ``` -This will automatically download `Dioxus-CLI` source from github master branch, -and install it in Cargo's global binary directory (`~/.cargo/bin/` by default). - -## Install from `crates.io` version +## Install the latest development build through git -The published version of the Dioxus CLI is updated less often, but should be more stable than the git version of the Dioxus CLI. +To get the latest bug fixes and features, you can install the development version from git. +However, this is not fully tested. +That means you're probably going to have more bugs despite having the latest bug fixes. ``` -cargo install dioxus-cli +cargo install --git https://github.com/DioxusLabs/dioxus dioxus-cli ``` + +This will download the CLI from the master branch, +and install it in Cargo's global binary directory (`~/.cargo/bin/` by default). + +Run `dx --help` for a list of all the available commands. +Furthermore, you can run `dx --help` to get help with a specific command. \ No newline at end of file diff --git a/docs-src/0.4/en/CLI/plugin/index.md b/docs-src/0.4/en/CLI/plugin/index.md index 9983f024b..26f70307f 100644 --- a/docs-src/0.4/en/CLI/plugin/index.md +++ b/docs-src/0.4/en/CLI/plugin/index.md @@ -1,24 +1,84 @@ -# CLI Plugin Development +# CLI Plugin development -> For Cli 0.2.0 we will add `plugin-develop` support. +**IMPORTANT: Ignore this documentation. Plugins are yet to be released and chances are it won't work for you. This is just what plugins *could* look like.** -Before the 0.2.0 we use `dioxus tool` to use & install some plugin, but we think that is not good for extend cli program, some people want tailwind support, some people want sass support, we can't add all this thing in to the cli source code and we don't have time to maintain a lot of tools that user request, so maybe user make plugin by themself is a good choice. +In the past we used `dx tool` to use and install tools, but it was a flawed system. +Tools were hard-coded by us, but people want more tools than we could code, so this plugin system was made to let +anyone develop plugins and use them in Dioxus projects. -### Why Lua ? +Plugin resources: +* [Source code](https://github.com/DioxusLabs/dioxus/tree/master/packages/cli/src/plugin) +* [Unofficial Dioxus plugin community](https://github.com/DioxusPluginCommunity). Contains certain plugins you can use right now. -We choose `Lua: 5.4` to be the plugin develop language, because cli plugin is not complex, just like a workflow, and user & developer can write some easy code for their plugin. We have **vendored** lua in cli program, and user don't need install lua runtime in their computer, and the lua parser & runtime doesn't take up much disk memory. +### Why Lua? -### Event Management +We chose Lua `5.4` to be the plugin developing language, +because it's extremely lightweight, embeddable and easy to learn. +We installed Lua into the CLI, so you don't need to do it yourself. -The plugin library have pre-define some important event you can control: +Lua resources: +* [Official website](https://www.lua.org/). You can basically find everything here. +* [Awesome Lua](https://github.com/LewisJEllis/awesome-lua). Additional resources (such as Lua plugins for your favorite IDE), and other *awesome* tools! -- `build.on_start` -- `build.on_finished` -- `serve.on_start` -- `serve.on_rebuild` -- `serve.on_shutdown` +## Creating a plugin -### Plugin Template +A plugin is just an `init.lua` file. +You can include other files using `dofile(path)`. +You need to have a plugin and a manager instance, which you can get using `require`: +```lua +local plugin = require("plugin") +local manager = require("manager") +``` + +You need to set some `manager` fields and then initialize the plugin: +```lua +manager.name = "My first plugin" +manager.repository = "https://github.com/john-doe/my-first-plugin" -- The repository URL. +manager.author = "John Doe " +manager.version = "0.1.0" +plugin.init(manager) +``` + +You also need to return the `manager`, which basically represents your plugin: +```lua +-- Your code here. +-- End of file. + +manager.serve.interval = 1000 +return manager +``` + +And you're ready to go. Now, go and have a look at the stuff below and the API documentation. + +### Plugin info + +You will encounter this type in the events below. The keys are as follows: +* `name: string` - The name of the plugin. +* `repository: string` - The plugin repository URL. +* `author: string` - The author of the plugin. +* `version: string` - The plugin version. + +### Event management + +The plugin library has certain events that you can subscribe to. + +* `manager.on_init` - Triggers the first time the plugin is loaded. +* `manager.build.on_start(info)` - Triggers before the build process. E.g., before `dx build`. +* `manager.build.on_finish(info)` - Triggers after the build process. E.g., after `dx build`. +* `manager.serve.on_start(info)` - Triggers before the serving process. E.g., before `dx serve`. +* `manager.serve.on_rebuild_start(info)` - Triggers before the server rebuilds the web with hot reload. +* `manager.serve.on_rebuild_end(info)` - Triggers after the server rebuilds the web with hot reload. +* `manager.serve.on_shutdown` - Triggers when the server is shutdown. E.g., when the `dx serve` process is terminated. + +To subscribe to an event, you simply need to assign it to a function: + +```lua +manager.build.on_start = function (info) + log.info("[plugin] Build starting: " .. info.name) +end +``` + +### Plugin template ```lua package.path = library_dir .. "/?.lua" @@ -76,4 +136,4 @@ end manager.serve.interval = 1000 return manager -``` \ No newline at end of file +``` diff --git a/docs-src/0.4/en/CLI/plugin/interface/command.md b/docs-src/0.4/en/CLI/plugin/interface/command.md index 86e539458..2882e5153 100644 --- a/docs-src/0.4/en/CLI/plugin/interface/command.md +++ b/docs-src/0.4/en/CLI/plugin/interface/command.md @@ -1,21 +1,21 @@ # Command Functions -> you can use command functions to execute some code & script +You can use command functions to execute code and scripts. -Type Define: +Type definition: ``` Stdio: "Inherit" | "Piped" | "Null" ``` ### `exec(commands: [string], stdout: Stdio, stderr: Stdio)` -you can use this function to run some command on the current system. +You can use this function to run some commands on the current system. ```lua local cmd = plugin.command manager.test = function () - cmd.exec({"git", "clone", "https://github.com/DioxusLabs/dioxus/tree/master/packages/cli-plugin-library"}) + cmd.exec({"git", "clone", "https://github.com/DioxusLabs/cli-plugin-library"}) end ``` -> Warning: This function don't have exception catch. \ No newline at end of file +> Warning: This function doesn't catch exceptions. \ No newline at end of file diff --git a/docs-src/0.4/en/CLI/plugin/interface/dirs.md b/docs-src/0.4/en/CLI/plugin/interface/dirs.md index bea3125ba..9984802ff 100644 --- a/docs-src/0.4/en/CLI/plugin/interface/dirs.md +++ b/docs-src/0.4/en/CLI/plugin/interface/dirs.md @@ -1,33 +1,28 @@ # Dirs Functions -> you can use Dirs functions to get some directory path +Dirs functions are for getting various directory paths. Not to be confused with `plugin.path`. +### `plugin_dir() -> string` -### plugin_dir() -> string - -You can get current plugin **root** directory path +Get the plugin's root directory path. ```lua local path = plugin.dirs.plugin_dir() -- example: ~/Development/DioxusCli/plugin/test-plugin/ ``` -### bin_dir() -> string - -You can get plugin **bin** directory path +### `bin_dir() -> string` -Sometime you need install some binary file like `tailwind-cli` & `sass-cli` to help your plugin work, then you should put binary file in this directory. +Get the plugin's binary directory path. Put binary files like `tailwind-cli` or `sass-cli` in this directory. ```lua local path = plugin.dirs.bin_dir() -- example: ~/Development/DioxusCli/plugin/test-plugin/bin/ ``` -### temp_dir() -> string - -You can get plugin **temp** directory path +### `temp_dir() -> string` -Just put some temporary file in this directory. +Get the plugin's temporary directory path. Put any temporary files here. ```lua local path = plugin.dirs.bin_dir() diff --git a/docs-src/0.4/en/CLI/plugin/interface/log.md b/docs-src/0.4/en/CLI/plugin/interface/log.md index fcd72595b..ee437b77a 100644 --- a/docs-src/0.4/en/CLI/plugin/interface/log.md +++ b/docs-src/0.4/en/CLI/plugin/interface/log.md @@ -1,46 +1,46 @@ # Log Functions -> You can use log function to print some useful log info +You can use log functions to print various logging information. -### Trace(info: string) +### `trace(info: string)` -Print trace log info +Print trace log info. ```lua local log = plugin.log log.trace("trace information") ``` -### Debug(info: string) +### `debug(info: string)` -Print debug log info +Print debug log info. ```lua local log = plugin.log log.debug("debug information") ``` -### Info(info: string) +### `info(info: string)` -Print info log info +Print info log info. ```lua local log = plugin.log log.info("info information") ``` -### Warn(info: string) +### `warn(info: string)` -Print warning log info +Print warning log info. ```lua local log = plugin.log log.warn("warn information") ``` -### Error(info: string) +### `error(info: string)` -Print error log info +Print error log info. ```lua local log = plugin.log diff --git a/docs-src/0.4/en/CLI/plugin/interface/network.md b/docs-src/0.4/en/CLI/plugin/interface/network.md index 358c9c498..566bc5073 100644 --- a/docs-src/0.4/en/CLI/plugin/interface/network.md +++ b/docs-src/0.4/en/CLI/plugin/interface/network.md @@ -1,12 +1,13 @@ # Network Functions -> you can use Network functions to download & read some data from internet +You can use Network functions to download & read some data from the internet. -### download_file(url: string, path: string) -> boolean +### `download_file(url: string, path: string) -> boolean` -This function can help you download some file from url, and it will return a *boolean* value to check the download status. (true: success | false: fail) +Downloads a file from the specified URL, +and returns a `boolean` that represents the download status (true: success, false: failure). -You need pass a target url and a local path (where you want to save this file) +You need to pass a target URL and a local path (where you want to save this file). ```lua -- this file will download to plugin temp directory @@ -19,9 +20,11 @@ if status != true then end ``` -### clone_repo(url: string, path: string) -> boolean +### `clone_repo(url: string, path: string) -> boolean` -This function can help you use `git clone` command (this system must have been installed git) +Clone a repository from the given URL into the given path. +Returns a `boolean` that represents the clone status (true: success, false: failure). +The system executing this function must have git installed. ```lua local status = plugin.network.clone_repo( diff --git a/docs-src/0.4/en/CLI/plugin/interface/os.md b/docs-src/0.4/en/CLI/plugin/interface/os.md index 72a17c336..84f4697b8 100644 --- a/docs-src/0.4/en/CLI/plugin/interface/os.md +++ b/docs-src/0.4/en/CLI/plugin/interface/os.md @@ -1,10 +1,10 @@ # OS Functions -> you can use OS functions to get some system information +OS functions are for getting system information. -### current_platform() -> string ("windows" | "macos" | "linux") +### `current_platform() -> string ("windows" | "macos" | "linux")` -This function can help you get system & platform type: +Get the current OS platform. ```lua local platform = plugin.os.current_platform() diff --git a/docs-src/0.4/en/CLI/plugin/interface/path.md b/docs-src/0.4/en/CLI/plugin/interface/path.md index ee787ecf9..a5bee1eb9 100644 --- a/docs-src/0.4/en/CLI/plugin/interface/path.md +++ b/docs-src/0.4/en/CLI/plugin/interface/path.md @@ -1,10 +1,13 @@ # Path Functions -> you can use path functions to operate valid path string +You can use path functions to perform operations on valid path strings. -### join(path: string, extra: string) -> string +### `join(path: string, extra: string) -> string` -This function can help you extend a path, you can extend any path, dirname or filename. + +Extend a path; you can extend both directory and file paths. ```lua local current_path = "~/hello/dioxus" @@ -12,9 +15,9 @@ local new_path = plugin.path.join(current_path, "world") -- new_path = "~/hello/dioxus/world" ``` -### parent(path: string) -> string +### `parent(path: string) -> string` -This function will return `path` parent-path string, back to the parent. +Return the parent path of the specified path. The parent path is always a directory. ```lua local current_path = "~/hello/dioxus" @@ -22,14 +25,14 @@ local new_path = plugin.path.parent(current_path) -- new_path = "~/hello/" ``` -### exists(path: string) -> boolean +### `exists(path: string) -> boolean` -This function can check some path (dir & file) is exists. +Check if the specified path exists, as either a file or a directory. -### is_file(path: string) -> boolean +### `is_file(path: string) -> boolean` -This function can check some path is a exist file. +Check if the specified path is a file. -### is_dir(path: string) -> boolean +### `is_dir(path: string) -> boolean` -This function can check some path is a exist dir. \ No newline at end of file +Check if the specified path is a directory. \ No newline at end of file diff --git a/docs-src/0.4/en/contributing/governence.md b/docs-src/0.4/en/contributing/governance.md similarity index 100% rename from docs-src/0.4/en/contributing/governence.md rename to docs-src/0.4/en/contributing/governance.md