From f203b5f99d7bed69f638073ac86fd911b14f2c19 Mon Sep 17 00:00:00 2001 From: YuKun Liu <41265098+mrxiaozhuox@users.noreply.github.com> Date: Sun, 24 Apr 2022 10:44:06 +0800 Subject: [PATCH] Move `docs` to cli repo --- .github/workflows/docs.yml | 32 ++++++++ docs/.gitignore | 1 + docs/book.toml | 6 ++ docs/src/SUMMARY.md | 11 +++ docs/src/cmd/README.md | 26 +++++++ docs/src/cmd/build.md | 47 ++++++++++++ docs/src/cmd/clean.md | 18 +++++ docs/src/cmd/serve.md | 49 +++++++++++++ docs/src/cmd/translate.md | 57 ++++++++++++++ docs/src/configure.md | 147 +++++++++++++++++++++++++++++++++++++ docs/src/creating.md | 38 ++++++++++ docs/src/installation.md | 24 ++++++ docs/src/introduction.md | 21 ++++++ 13 files changed, 477 insertions(+) create mode 100644 .github/workflows/docs.yml create mode 100644 docs/.gitignore create mode 100644 docs/book.toml create mode 100644 docs/src/SUMMARY.md create mode 100644 docs/src/cmd/README.md create mode 100644 docs/src/cmd/build.md create mode 100644 docs/src/cmd/clean.md create mode 100644 docs/src/cmd/serve.md create mode 100644 docs/src/cmd/translate.md create mode 100644 docs/src/configure.md create mode 100644 docs/src/creating.md create mode 100644 docs/src/installation.md create mode 100644 docs/src/introduction.md diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 000000000..2638b8a18 --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,32 @@ +name: github pages + +on: + push: + paths: + - docs/** + - .github/workflows/docs.yml + branches: + - master + +jobs: + build-deploy: + runs-on: ubuntu-latest + environment: docs + steps: + - uses: actions/checkout@v2 + + - name: Setup mdBook + uses: peaceiris/actions-mdbook@v1 + with: + mdbook-version: "0.4.10" + + - name: Build + run: cd docs && md build -d ../build + + - name: Deploy 🚀 + uses: JamesIves/github-pages-deploy-action@v4.2.3 + with: + branch: gh-pages # The branch the action should deploy to. + folder: build # The folder the action should deploy. + clean: false + token: ${{ secrets.DEPLOY_KEY }} # let's pretend I don't need it for now diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 000000000..7585238ef --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1 @@ +book diff --git a/docs/book.toml b/docs/book.toml new file mode 100644 index 000000000..c5c216fe4 --- /dev/null +++ b/docs/book.toml @@ -0,0 +1,6 @@ +[book] +authors = ["YuKun Liu"] +language = "en" +multilingual = false +src = "src" +title = "Dioxus Cli" diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md new file mode 100644 index 000000000..ed7bcbfaf --- /dev/null +++ b/docs/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) \ No newline at end of file diff --git a/docs/src/cmd/README.md b/docs/src/cmd/README.md new file mode 100644 index 000000000..c642b475f --- /dev/null +++ b/docs/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] + +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 +``` \ No newline at end of file diff --git a/docs/src/cmd/build.md b/docs/src/cmd/build.md new file mode 100644 index 000000000..e81973f2d --- /dev/null +++ b/docs/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 [default: ""] + --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 +``` \ No newline at end of file diff --git a/docs/src/cmd/clean.md b/docs/src/cmd/clean.md new file mode 100644 index 000000000..2f889c1a8 --- /dev/null +++ b/docs/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 +``` + diff --git a/docs/src/cmd/serve.md b/docs/src/cmd/serve.md new file mode 100644 index 000000000..e5c10a902 --- /dev/null +++ b/docs/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 [default: ""] + --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 +``` \ No newline at end of file diff --git a/docs/src/cmd/translate.md b/docs/src/cmd/translate.md new file mode 100644 index 000000000..415a88fba --- /dev/null +++ b/docs/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 file, stdout if not present + +OPTIONS: + -c, --component Activate debug mode + -f, --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 +
+

Hello World

+ Link +
+``` + +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" + } + } + }) +} +``` \ No newline at end of file diff --git a/docs/src/configure.md b/docs/src/configure.md new file mode 100644 index 000000000..f274ce70d --- /dev/null +++ b/docs/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 `` 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 = [] +``` \ No newline at end of file diff --git a/docs/src/creating.md b/docs/src/creating.md new file mode 100644 index 000000000..fa725a4f7 --- /dev/null +++ b/docs/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 +``` \ No newline at end of file diff --git a/docs/src/installation.md b/docs/src/installation.md new file mode 100644 index 000000000..7151de1ff --- /dev/null +++ b/docs/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`. \ No newline at end of file diff --git a/docs/src/introduction.md b/docs/src/introduction.md new file mode 100644 index 000000000..2f857a2a5 --- /dev/null +++ b/docs/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) \ No newline at end of file