|
| 1 | +# User Manual |
| 2 | + |
| 3 | +**Try it [here (experimental)](https://app.codepod.io)** |
| 4 | + |
| 5 | +## Optional User Registration |
| 6 | + |
| 7 | +Codepod is a web app with standard user authentication. You can register, or better, you can login with your google account instantly. If you don't register & login, the system will register a Guest user, so that people can try out Codepod without registering. |
| 8 | + |
| 9 | +<img src={require("./assets/signup.png").default} alt="xxx" width="600" /> |
| 10 | + |
| 11 | +## The dashboard and project creation |
| 12 | + |
| 13 | +You will be greeted with the dashboard. It will list your projects and those that shared with you by other users. You can create a new project on the dashboard, which drops you into the new project canvas. |
| 14 | + |
| 15 | +<!--  --> |
| 16 | + |
| 17 | +<img src={require("./assets/guestUser.png").default} alt="xxx" width="600" /> |
| 18 | + |
| 19 | +## The Canvas |
| 20 | + |
| 21 | +### Create your first code pod |
| 22 | + |
| 23 | +In the canvas, you can right-click on the Canvas to create pods and scopes. Create a new pod, and you can type your hello world code in the cell. |
| 24 | + |
| 25 | +<!--  --> |
| 26 | + |
| 27 | +<img |
| 28 | +src={require("./assets/create-pod.png").default} |
| 29 | +alt="Example banner" |
| 30 | +width="600" |
| 31 | +/> |
| 32 | + |
| 33 | +### The runtime and sidebar |
| 34 | + |
| 35 | +The sidebar shows some status of the project and runtime, as well as settings. Wait until you have the runtime ready and idle for running code. The sidebar can be folded with the "Fold" button. |
| 36 | + |
| 37 | +### Execute the code |
| 38 | + |
| 39 | +Back to your code, you can execute the pod by clicking the "run" button on the floating toolbar, or press `<shift>+<enter>`. |
| 40 | + |
| 41 | +<img |
| 42 | +src={require("./assets/execute.png").default} |
| 43 | +alt="Example banner" |
| 44 | +width="600" |
| 45 | +/> |
| 46 | + |
| 47 | +### Moving around the Canvas |
| 48 | + |
| 49 | +You can move your pods with the drag handles on the toolbar. Simply drag-n-drop. |
| 50 | + |
| 51 | +## Organize your Canvas with scopes |
| 52 | + |
| 53 | +### Create your first scope |
| 54 | + |
| 55 | +One key feature that Codepod brings is the scope. You can create a scope by right-clicking on the canvas. Scopes are like modules in your code, they can be nested, and you can move your pods into scopes. Drag-n-drop your pods into the scope; a target scope will be highlighted when you drag a pod over it. |
| 56 | + |
| 57 | +<img |
| 58 | +src={require("./assets/moveIntoScope.png").default} |
| 59 | +alt="Example banner" |
| 60 | +width="600" |
| 61 | +/> |
| 62 | + |
| 63 | +You can also run all the pods in the scope by clicking the "Run" button in the scope toolbar. It will execute all pods and scopes in the scope by geometric order, from top-left to bottom-right. |
| 64 | + |
| 65 | +<img src={require("./assets/executeScope.png").default} alt="xxx" width="600" /> |
| 66 | + |
| 67 | +### The scoped runtime semantics |
| 68 | + |
| 69 | +The scoped runtime supports python variables, functions, and classes. You can define them in the scope, and use them in the pods. The scope is like a python module. All names defined in the scope stays inside the scope. The outside world cannot see it. |
| 70 | + |
| 71 | +### Export to parent as public API |
| 72 | + |
| 73 | +A scope can define some public APIs, which can be used by outer scopes. You can define a public API by adding a `@export` decorator at the first line of the pod. Once you execute it, the pod will be highlighted with a thick green border to indicate that this pod defines a public API. The public API can then be resolved in outer scope. |
| 74 | + |
| 75 | +<img |
| 76 | +src={require("./assets/scopeExport.png").default} |
| 77 | +alt="Example banner" |
| 78 | +width="600" |
| 79 | +/> |
| 80 | + |
| 81 | +The names can be further exported to ancestor nodes. |
| 82 | + |
| 83 | +<img |
| 84 | +src={require("./assets/scopeRecursiveExport.png").default} |
| 85 | +alt="Example banner" |
| 86 | +width="600" |
| 87 | +/> |
| 88 | + |
| 89 | +### Lexical scoping |
| 90 | + |
| 91 | +The other direction, from parent scope to child scope, is automatic. It works like the lexical scoping where inner scopes can see the names in outer scopes. This enables you to define global variables and utility functions in the outermost scope, and use them anywhere on the Canvas. |
| 92 | + |
| 93 | +<img |
| 94 | +src={require("./assets/parentToChild.png").default} |
| 95 | +alt="Example banner" |
| 96 | +width="600" |
| 97 | +/> |
| 98 | + |
| 99 | +## Writing docs in Rich-text editor |
| 100 | + |
| 101 | +We integrate the Remirror/ProseMirror editor, so that you can write rich-text documents in the pods. You can create a rich-text pod by right-clicking on the canvas. The rich-text pod supports markdown syntax, and you can insert images and videos. |
| 102 | + |
| 103 | +<img |
| 104 | +src={require("./assets/richText.png").default} |
| 105 | +alt="Example banner" |
| 106 | +width="600" |
| 107 | +/> |
| 108 | + |
| 109 | +The rich-text editor supports: |
| 110 | + |
| 111 | +- Markdown syntax |
| 112 | +- Insert images |
| 113 | +- Tables |
| 114 | +- Links |
| 115 | + |
| 116 | +## Copy-n-paste |
| 117 | + |
| 118 | +You can copy a pod or a scope, and paste it anywhere on the canvas. The copy-n-paste feature is in the pod toolbar. You can also paste across browser tabs. On paste, a shadowed visualization will be moving with your cursor until you click to drop it. |
| 119 | + |
| 120 | +<img src={require("./assets/copyNPaste.png").default} alt="xxx" width="600" /> |
| 121 | + |
| 122 | +## Auto-layout |
| 123 | + |
| 124 | +It is painful and inefficient to resize and position the pods and scopes manually. Codepod provides an auto-layout feature to help you organize your canvas. The auto-layout setting is in the sidebar, default to enabled. |
| 125 | + |
| 126 | +Before auto-layout, the pods and scopes could be overlapped and messy. |
| 127 | + |
| 128 | +<img |
| 129 | +src={require("./assets/autoLayoutBefore.png").default} |
| 130 | +alt="Example banner" |
| 131 | +width="600" |
| 132 | +/> |
| 133 | + |
| 134 | +After auto-layout, the pods and scopes are organized by a collision-free algorithm, and the scopes will be resized to fit the pods inside. |
| 135 | + |
| 136 | +<img |
| 137 | +src={require("./assets/autoLayoutAfter.png").default} |
| 138 | +alt="xxx" |
| 139 | +width="600" |
| 140 | +/> |
| 141 | + |
| 142 | +## Contextual zooming |
| 143 | + |
| 144 | +The canvas can be zoomed in and out by the touch pad pining, the buttons, and the mouse wheel. We introduce a major feature called "contextual zoom". The idea is to see different level of details at different zoom levels, so that users can focus on a small subsets of content to work on. Think of it as Google maps where you zoom in & out to see different levels of details. |
| 145 | + |
| 146 | +The feature contains roughly two significant behaviors: |
| 147 | + |
| 148 | +1. different levels in the hierarchy have different font sizes |
| 149 | +2. when zooming out, the pods and scopes that become too small to view will be collapsed into a block, with large text summarizing its content. These blocks can be dragged and moved easily (which is pretty easy to use). |
| 150 | + |
| 151 | +This feature is experimental and disabled by default. There's a setting contextual zoom in the sidebar to enable it. |
| 152 | + |
| 153 | +Fully expanded (zoomed in): |
| 154 | + |
| 155 | +<img src={require("./assets/zoomExpanded.png").default} alt="xxx" width="600" /> |
| 156 | + |
| 157 | +Zoom out: |
| 158 | + |
| 159 | +<img src={require("./assets/zoom1.png").default} alt="xxx" width="600" /> |
| 160 | + |
| 161 | +Zoom out: |
| 162 | + |
| 163 | +<img src={require("./assets/zoom2.png").default} alt="xxx" width="600" /> |
| 164 | + |
| 165 | +Zoom out: |
| 166 | + |
| 167 | +<img src={require("./assets/zoomAll.png").default} alt="xxx" width="600" /> |
| 168 | + |
| 169 | +## Exporting |
| 170 | + |
| 171 | +You can export your project into a SVG image, executable Python files, and a Jupyter notebook. The export button is in the sidebar. |
| 172 | + |
| 173 | +## Share your project and collaborate in real time |
| 174 | + |
| 175 | +Modern collaboration cannot be without real-time collaboration. Codepod supports real-time collaboration. You can share your project with other users, and they can edit the project together with you in real time. |
| 176 | + |
| 177 | +<img src={require("./assets/shareDialog.png").default} alt="xxx" width="600" /> |
| 178 | + |
| 179 | +The shared projects will be shown in the bottom of the Guest's dashboard. The real-time collaboration happens in the following places: |
| 180 | + |
| 181 | +- The code pods |
| 182 | +- The rich-text pods |
| 183 | +- The Canvas: nodes and edges |
| 184 | + |
| 185 | +## In case of the app went wrong |
| 186 | + |
| 187 | +The project is still in heavy development, and bugs can happen. If you find the page is not responding, you can try to refresh the page. |
| 188 | + |
| 189 | +If you would like to hunter the bugs, welcome and thanks! You can open the developer console and see if there are errors. Let us know by openning a GitHub issue. |
0 commit comments