Merge pull request #269 from mrxiaozhuox/master

Add `Dioxus-cli` Document

README.md

@@ -44,7 +44,7 @@
     <span> | </span>
     <a href="https://dioxuslabs.com/guide"> Guide (0.1.8) </a>
     <span> | </span>
-    <a href="https://dioxuslabs.com/nightly/guide"> Guide (Master) </a>
+    <a href="https://dioxuslabs.com/nightly/guide"> Guide (Nightly) </a>
   </h3>
 </div>
 

docs/cli/.gitignore

@@ -0,0 +1 @@
+book

docs/cli/book.toml

@@ -0,0 +1,6 @@
+[book]
+authors = ["YuKun Liu"]
+language = "en"
+multilingual = false
+src = "src"
+title = "Dioxus Cli"

docs/cli/src/SUMMARY.md

@@ -0,0 +1,11 @@
+# Summary
+
+- [Introduction](./introduction.md)
+- [Installation](./installation.md)
+- [Create a Project](./creating.md)
+- [Configure Project](./configure.md)
+- [Commands](./cmd/README.md)
+  - [Build](./cmd/build.md)
+  - [Serve](./cmd/serve.md)
+  - [Clean](./cmd/clean.md)
+  - [Translate](./cmd/translate.md)

docs/cli/src/cmd/README.md

@@ -0,0 +1,26 @@
+# 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] <SUBCOMMAND>
+
+OPTIONS:
+    -h, --help    Print help information
+    -v            Enable verbose logging
+
+SUBCOMMANDS:
+    build        Build the Rust WASM app 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 source file into Dioxus code
+```

docs/cli/src/cmd/build.md

@@ -0,0 +1,47 @@
+# Build
+
+The `dioxus build` command can help you `pack & build` a dioxus project.
+
+```
+dioxus-build 
+Build the Rust WASM app and all of its assets
+
+USAGE:
+    dioxus build [OPTIONS]
+
+OPTIONS:
+        --example <EXAMPLE>      [default: ""]
+        --platform <PLATFORM>    [default: "default_platform"]
+        --release                [default: false]
+```
+
+You can use this command to build project to `out_dir` :
+
+```
+dioxus build --release
+```
+
+## Target platform
+
+Use option `platform` choose build target platform:
+
+```
+# for desktop project
+dioxus build --platform desktop
+```
+
+`platform` only supports `desktop` & `web`.
+
+```
+# for web project
+dioxus build --platform web
+```
+
+## Build Example
+
+You can use `--example {name}` to build a example code.
+
+```
+# build `example/test` code
+dioxus build --exmaple test
+```

docs/cli/src/cmd/clean.md

@@ -0,0 +1,18 @@
+# Clean
+
+`dioxus clean` will call `target clean` and remove `out_dir` directory.
+
+```
+dioxus-clean 
+Clean output artifacts
+
+USAGE:
+    dioxus clean
+```
+
+you can use this command to clean all build cache and the `out_dir` content.
+
+```
+dioxus clean
+```
+

docs/cli/src/cmd/serve.md

@@ -0,0 +1,49 @@
+# Serve
+
+The `dioxus serve` can start a dev server (include hot-reload tool) to run the project.
+
+```
+dioxus-serve 
+Build, watch & serve the Rust WASM app and all of its assets
+
+USAGE:
+    dioxus serve [OPTIONS]
+
+OPTIONS:
+        --example <EXAMPLE>      [default: ""]
+        --platform <PLATFORM>    [default: "default_platform"]
+        --release                [default: false]
+```
+
+You can use this command to build project and start a `dev server` :
+
+```
+dioxus serve
+```
+
+## Target platform
+
+Use option `platform` choose build target platform:
+
+```
+# for desktop project
+dioxus serve --platform desktop
+```
+
+`platform` only supports `desktop` & `web`.
+
+`dev-server` only for `web` project.
+
+```
+# for web project
+dioxus serve --platform web
+```
+
+## Serve Example
+
+You can use `--example {name}` to start a example code.
+
+```
+# build `example/test` code
+dioxus serve --exmaple test
+```

docs/cli/src/cmd/translate.md

@@ -0,0 +1,57 @@
+# Translate
+
+`dioxus translate` can translate some source file into Dioxus code.
+
+```
+dioxus-translate 
+Translate some source file into Dioxus code
+
+USAGE:
+    dioxus translate [OPTIONS] [OUTPUT]
+
+ARGS:
+    <OUTPUT>    Output file, stdout if not present
+
+OPTIONS:
+    -c, --component      Activate debug mode
+    -f, --file <FILE>    Input file
+```
+
+## Translate HTML to stdout
+
+```
+dioxus transtale --file ./index.html
+```
+
+## Output in a file
+
+```
+dioxus translate --component --file ./index.html component.rsx
+```
+
+set `component` flag will wrap `dioxus rsx` code in a component function.
+
+## Example
+
+```html
+<div>
+    <h1> Hello World </h1>
+    <a href="https://dioxuslabs.com/">Link</a>
+</div>
+```
+
+Translate HTML to Dioxus component code.
+
+```rust
+fn component(cx: Scope) -> Element {
+    cx.render(rsx! {
+        div {
+            h1 { "Hello World" },
+            a {
+                href: "https://dioxuslabs.com/",
+                "Link"
+            }
+        }
+    })
+}
+```

docs/cli/src/configure.md

@@ -0,0 +1,147 @@
+# Configure Project
+
+This chapter will introduce `Dioxus.toml` and anatomy the config file.
+
+## Structure
+
+We use `toml` to define some info for `dioxus` project.
+
+### Application
+
+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 `dioxus build & serve` will default build desktop app.
+3. ***out_dir*** - which directory to put the output file; use `dioxus 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"
+   ```
+
+### Web.App
+
+Web platform application config:
+
+1. ***title*** - this value will display on the web page title. like `<title></title>` tag.
+   ```
+   # HTML title tag content
+   title = "dioxus app | ⛺"
+   ```
+
+### Web.Watcher
+
+Web platform `dev-server` watcher config:
+
+1. ***reload_html*** - a boolean value; when watcher trigger, regenerate `index.html` file.
+   ```
+   # when watcher trigger, regenerate the `index.html`
+   reload_html = true
+   ```
+2. ***watch_path*** - which files & directories will be watcher monitoring.
+   ```
+   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"
+    ]
+   ```
+
+### Web.Resource.Dev
+
+Only include resources at `Dev` mode.
+
+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"
+    ]
+   ```
+
+## Config example
+
+```toml
+[application]
+
+# App (Project) Name
+name = "{{project-name}}"
+
+# Dioxus App Default Platform
+# desktop, web, mobile, ssr
+default_platform = "web"
+
+# `build` & `serve` dist path
+out_dir = "dist"
+
+# resource (public) file folder
+asset_dir = "public"
+
+[web.app]
+
+# HTML title tag content
+title = "dioxus | ⛺"
+
+[web.watcher]
+
+# when watcher trigger, regenerate the `index.html`
+reload_html = true
+
+# which files or dirs will be watcher monitoring
+watch_path = ["src", "public"]
+
+# include `assets` in web platform
+[web.resource]
+
+# CSS style file
+style = []
+
+# Javascript code file
+script = []
+
+[web.resource.dev]
+
+# serve: [dev-server] only
+
+# CSS style file
+style = []
+
+# Javascript code file
+script = []
+```

docs/cli/src/creating.md

@@ -0,0 +1,38 @@
+# Create a Project
+
+Once you have the Dioxus CLI tool installed, you can use it to create dioxus project.
+
+## Initializing a default project
+
+The `dioxus create` command will create a new directory containing a project template.
+```
+dioxus 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.
+
+then you can change the current directory in to the project:
+
+```
+cd hello-dioxus
+```
+
+> Make sure `wasm32 target` is installed before running the Web project.
+
+now we can create a `dev server` to display the project:
+
+```
+dioxus serve
+```
+
+by default, the dioxus dev server will running at: [`http://127.0.0.1:8080/`](http://127.0.0.1:8080/)
+
+## Initalizing from other repository
+
+you can assign which repository you want to create:
+
+```
+dioxus init hello-dioxus --template=gh:dioxuslabs/dioxus-template
+```

docs/cli/src/installation.md

@@ -0,0 +1,24 @@
+# Installation
+
+There are multiple ways to install the Dioxus CLI tool. Choose any one of the methods below that best suit your needs.
+
+## Install from latest master version
+
+We suggest you use `github master` version to install it now.
+
+We have not yet released the latest version to `crates.io`
+
+```
+cargo install --git https://github.com/Dioxuslabs/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
+
+```
+cargo install dioxus-cli
+```
+
+Make sure to add the Cargo bin directory to your `PATH`.

docs/cli/src/introduction.md

@@ -0,0 +1,21 @@
+# Introduction
+
+📦✨ **Dioxus-Cli** is a tool to help 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.
+
+## 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)