swaits/dioxus
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Improve CLI docs (#1404)

Browse Source 
* Improve CLI docs

* Fixed all the typos (hopefully).
* Improved the bad English. This encompasses grammar, vocabulary, generally awkward phrases, etc. The result is easier to read and understand, and in some cases shorter.
* Made some formatting improvements. This includes making formatting more consistent, but I changed some of it to be better, at least in my opinion.
* Removed certain unnecessities, the biggest one being the commands documentation. I think this is unnecessary because of the `dx --help` command. It also needs to be updated every time a command gets added/updated/removed. It doesn't really provide much extra insight than `dx --help`.
* Improved plugin documentation. I added a warning to ignore all of it, which is ironic, but the fact is that plugins are probably going to change. But by the time I learned that, I already made some changes to the plugin docs. This includes a better guide on how to get started (although still bad since the plugin system is too messy), and some general changes like the aforementioned English or formatting.
* And more. I can't list it all, but I didn't use any destructive changes. The content might be reformatted (to be shorter or easier to understand), but the meaning isn't lost.

* Fix grammar in packages/cli/docs/src/creating.md

Co-authored-by: Evan Simkowitz <esimkowitz@users.noreply.github.com>

* Update README.md

* Change config example

---------

Co-authored-by: Evan Simkowitz <esimkowitz@users.noreply.github.com>
This commit is contained in:
LeonardandEvan Simkowitz authored and GitHub committed 2023-09-02 17:59:20 -05:00
1 parent a0d1e5de3a
commit 94f76946fc
20 files changed
+308 -488
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

packages/cli/docs/src/plugin/README.md
+74 -13
View File
@@ -1,24 +1,85 @@
# 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 `dx 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`
### Plugin Template
## Creating a plugin
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 <john.doe@example.com>"
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"
packages/cli/docs/src/plugin/interface/command.md
+4 -4
View File
@@ -1,15 +1,15 @@
# 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
@@ -18,4 +18,4 @@ manager.test = function ()
cmd.exec({"git", "clone", "https://github.com/DioxusLabs/cli-plugin-library"})
end
```
> Warning: This function don't have exception catch.
> Warning: This function doesn't catch exceptions.
packages/cli/docs/src/plugin/interface/dirs.md
+7 -12
View File
@@ -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
### `bin_dir() -> string`
You can get plugin **bin** direcotry path
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
### `temp_dir() -> string`
You can get plugin **temp** direcotry path
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()
packages/cli/docs/src/plugin/interface/log.md
+11 -11
View File
@@ -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
packages/cli/docs/src/plugin/interface/network.md
+9 -6
View File
@@ -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(
packages/cli/docs/src/plugin/interface/os.md
+3 -3
View File
@@ -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()
packages/cli/docs/src/plugin/interface/path.md
+14 -11
View File
@@ -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.
<!-- TODO: Add specifics.
From the example given, it seems like it just creates a subdirectory path.
What would it do when "extending" file paths? -->
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.
Check if the specified path is a directory.