update document

README.md

@@ -7,11 +7,14 @@ A cross-platform [Rez](https://github.com/nerdvegas/rez) production tooling mana
 
 <img src="https://user-images.githubusercontent.com/3357009/130851292-2510bb0e-7fc5-409e-bfbb-e38ab4086d11.gif" width="610"></img>
 
+[Read The Docs](https://davidlatwe.github.io/rezup/)
+
 
 ## Why use rezup
 
-* Simplify Rez venv setup and update process
-* Easier to manage Rez tooling
+* Easier to setup/update Rez venv
+* Easier to install custom Rez extensions (plugins)
+* Easier to provide different Rez venv setup for different purpose
 
 
 ## Install
@@ -30,24 +33,29 @@ $ pip install -U rezup-api
 
 ## Quick start
 
-Call `rezup` in your terminal
+Simply calling `rezup` in terminal will suffice.
 
 ```shell
 $ rezup
 ```
 
-What will/should happen ?
+The command above is a shorthand for `rezup use .main`, which means to enter a Rez venv container named `.main`. Usually you must `rezup add` a new container before you can use it. But default container `.main` will automatically be created if it's not existing yet, for the first time.
+
+So, what will & should happen after calling `rezup` ?
+
+1. A most basic recipe will be written into user home directory (`~/rezup.toml`)
+2. Default container `.main` will be created with that recipe
+3. Wait for it...
+4. Bam! A vanilla Rez environment is presented (In subprocess)
+5. Try `rez --version` or any `rez` command
+6. Once you're done, simply type `exit` to escape.
 
-1. For first time quick-start, calling `rezup` will create a default container
-2. So wait for it...
-3. Bam! A vanilla Rez environment is presented (In subprocess)
-4. Try `rez --version` or any `rez` command
-5. Once you're done, simply type `exit` to escape.
+As you may have seen, Rez venv is in the container and is deployed with a recipe file. Please visit [Container-Recipe](https://davidlatwe.github.io/rezup/container/#recipe) page for more detail about how you can auth and create a richer container by the recipe.
 
-To know more, please run `rezup --help` or `rezup [COMMAND] --help` for each command's usage.
+And for other rezup commands, please run `rezup --help` or `rezup [COMMAND] --help` for each command's usage.
 
 ```shell
 $ rezup --help
 ```
 
-Or, [Read The Docs](https://davidlatwe.github.io/rezup/)
+Or, visit [Command](https://davidlatwe.github.io/rezup/command/) page.

docs/container.md

@@ -0,0 +1,224 @@
+
+## Structure
+
+A *container* provides Rez environment from it's *revision*.
+
+Each container holds at least one virtual environment folder that named by timestamp, which is a *revision*. With that convention, the latest version of environment can be sorted out and used without affecting existing container user.
+
+```
+~\.rezup                 # container root
+   |
+   + - {container}
+   |     :
+   :     :
+   :     + - {revision}  # venv and bin tools lives here
+   :     |
+         + - {revision}  # folder named as timestamp, e.g. 1619780350.58
+         |
+         + - {revision}  # take latest when calling `rezup use {container}`
+
+
+```
+
+## Remote Container
+
+To manage Rez venv in production, we may want every machine to have the same Rez venv setup and try keeping them up-to-date.
+
+For this purpose, a centralized remote container is needed as a guidance for `rezup use` command to pick the right Rez venv setup from there, and create it locally if needed.
+
+!!! question "How that works ?"
+
+    When calling `rezup use {container}`, if the container has remote set, rezup will find the latest valid revision from remote and see if the same revision exists in local and use it. If not, create a new one by the recipe in that remote revision before use.
+
+    But what if local container contains revisions that doesn't exists in remote ?
+
+    The command `rezup use` always respect remote revision even there's more latest revision exists in local. Unless `rezup use --local` is used and remote will be ignored.
+
+!!! info "The Difference"
+
+    Both local and remote container have the same structure, the difference is the payload.
+
+    === "Local"
+        Where the Rez venv actually exists. Can be created by command
+        ```
+        rezup add {container}
+        ```
+
+    === "Remote"
+        Only contains the venv installation manifest file (recipe) `rezup.toml` that uploaded by command
+        ```
+        rezup add {container} --remote
+        ```
+
+!!! tip "Local doesn't have to be in local"
+
+    Local container root can be pointed into network drive, but if that's how it setup, keeps an eye on which Python interpreter is being used or the venv may not be usable.
+
+
+## Recipe
+
+A recipe file defines how a Rez venv should be built.
+
+### File Naming
+
+Recipe files usually be saved to and loaded from user home directory, and should be named with container (if not default container) so that command `rezup add <container>` could pick it up when creating corresponding container, for example:
+
+* `~/rezup.toml` for container `.main`, the default
+* `~/rezup.dev.toml` for container `dev`
+* `~/rezup.test.toml` for container `test`
+* `~/rezup.{name}.toml` for container `{name}`
+
+### File Content
+
+A recipe file may look like the following example, see below for details about each section.
+
+```toml
+description = "My rez setup"
+
+[root]
+local = false
+remote = false
+
+[dotenv]
+
+[env]
+REZ_CONFIG_FILE = "/path/to/rezconfig.py"
+MY_CUSTOMS_ENV = "my value"
+
+[rez]
+name = "rez"
+url = "rez>=2.83"   # a PyPi version specifier or repository path
+
+[[extension]]
+name = "foo"
+url = "~/dev/foo"
+edit = true         # install this in edit mode (pip --edit)
+
+[[extension]]
+name = "bar"
+url = "git+git://github.com/get-bar/bar"
+isolation = true    # additional venv will be created just for this package
+python = 2.7        # the python version for the venv of this package
+
+[shared]
+name = "production"
+requires = [
+    "pyside2",
+    "Qt5.py",
+]
+
+```
+
+
+#### description
+
+```toml
+description = "hello, Rez!"
+```
+
+Like a comment, for knowing what this recipe is for.
+
+
+#### root
+
+Define where the root of this container should be.
+
+```toml
+[root]
+local = ""
+remote = "/studio/remote/.rezup"
+```
+
+=== "local"
+    If the value is `false` or empty string `""`, env var `REZUP_ROOT_LOCAL` will be used, or the default `~/.rezup`.
+
+=== "remote"
+    If the value is `false` or empty string `""`, env var `REZUP_ROOT_REMOTE` will be used, or no remote for this container.
+
+
+#### dotenv
+
+The `.env` files will be loaded in order when container revision is being used, if provided.
+
+```toml
+[dotenv]
+1 = "/to/my.env"    # non platform specific, load firstly, sort by key
+2 = "/to/other.env"
+[dotenv.linux]
+a = "/to/lnx.env"   # platform specific, load secondly, sort by key
+[dotenv.darwin]
+a = "/to/mac.env"   # platform specific, load secondly, sort by key
+[dotenv.windows]
+a = "/to/win.env"   # platform specific, load secondly, sort by key
+```
+
+The key can be anything, they are only for sorting.
+
+
+#### env
+
+These will be loaded when container revision is being used, if provided.
+
+```toml
+[env]
+REZ_CONFIG_FILE = "/path/to/rezconfig.py"
+```
+
+
+#### rez
+
+Rez venv setup configurations
+
+```toml
+[rez]
+# required
+name = "rez"
+url = "/path/to/source/rez"
+# optional
+edit = true
+flags = ["-E"]
+python = 3.7
+```
+
+|Name|Required|Description
+| :---: | :---: | --- |
+|name| O | The name of the package |
+|url| O | The url that pass to `pip install`. Could be version specifier like `rez>=2.90`, or from version control like `git+https://github.com/nerdvegas/rez`, or local source path.|
+|edit| - | Just like `pip install -e`, install package in edit mode or not. |
+|python| - | The Python to create venv with. Use current if not set. Could be path to Python executable, or version |
+|flags| - | Python interpreter flags, default `["-E"]` if not set. No flag will be added if the value is an empty list. |
+
+
+#### extension
+
+```toml
+[[extension]]      # note this is a list but it's name is not plural
+# required
+name = "foo"
+url = "foo>=0.5"
+# optional
+edit = false
+flags = ["-E"]
+isolation = true
+python = 3.10      # ignored if `isolation` is false
+```
+
+Just like the section `rez`, but there's an extra option `isolation` can be used. Shouldn't be needed in most cases though.
+
+If `isolation` is true, a venv will be created just for this extension with Rez installed as lib into it. If false as default, the extension will be installed into the Rez venv.
+
+
+#### shared
+
+```toml
+[shared]
+name = "production"
+requires = [
+    "pyside2",
+    "Qt5.py",
+]
+```
+
+For faster deploy, dependency packages can be installed in here, and will be shared across all revisions in one container (all revisions that use same `name` of shared lib).
+
+This works by creating a `.pth` file that contains the absolute path of shared lib in Rez venv and only that venv. So this will not be shared with the extension that has `isolation` set to true.

docs/environ.md

@@ -3,8 +3,8 @@
 
 |Name|Description|
 | --- | --- |
-|REZUP_ROOT_LOCAL|Root path of local containers, default is `~/.rezup`|
-|REZUP_ROOT_REMOTE|Root path of remote containers|
+|REZUP_ROOT_LOCAL|Root path of local containers, if not defined in [Recipe](../container#root), default is `~/.rezup`|
+|REZUP_ROOT_REMOTE|Root path of remote containers, if not defined in [Recipe](../container#root)|
 |REZUP_DEFAULT_SHELL|Specify shell to use. See [Command](../command#shell-detection).|
 |REZUP_PROMPT|For customizing shell prompt, optional. See [Command](../command#shell-prompt).|
 |REZUP_CONTAINER|Auto set, for customizing shell prompt. See [Command](../command#shell-prompt).|

docs/rezup.md

@@ -5,6 +5,13 @@
 
 ::: rezup.recipe.ContainerRecipe
 
+
+# get_container_root
+
+*Internal use*
+
+::: rezup.container.get_container_root
+
 # Container
 
 ::: rezup.container.Container

docs/scripts.md

@@ -14,6 +14,8 @@ env = util.resolve_environ(revision, ["pkg_a", "pkg_b"])
 
 !!! tip "Provisional recipes"
 
+    By default, all recipe files should be in user home directory and only there will be looked for. But in some cases, you may want to provide your own *remotely*. 
+
     ```python
     from rezup import util, ContainerRecipe