Add expressions and table docs, general docs cleanup

Signed-off-by: Andrew Stein <[email protected]>

docs/docs/development.md → DEVELOPMENT.md

@@ -1,11 +1,6 @@
----
-id: development
-title: Developer Guide
----
-
-Thank you for your interest in contributing to Perspective! This guide will
-teach you everything you need to know to get started hacking on the Perspective
-codebase.
+This guide will teach you everything you need to know to get started hacking on
+the Perspective codebase. Please see [`CONTRIBUTING.md`](CONTRIBUTING.md) for
+contribution guidelines.
 
 If you're coming to this project as principally a JavaScript developer, please
 be aware that Perspective is quite a bit more complex than a typical NPM package

README.md

@@ -37,19 +37,15 @@ and/or [Jupyterlab](https://jupyterlab.readthedocs.io/en/stable/).
 ### Documentation
 
 - [Project Site](https://perspective.finos.org/)
-- User Guides
- - [Javascript User Guide](https://perspective.finos.org/docs/js.html)
- - [Python User Guide](https://perspective.finos.org/docs/python.html)
- - [Developer Guide](https://perspective.finos.org/docs/development.html)
-- Concepts
- - [Table](https://perspective.finos.org/docs/table.html)
- - [View](https://perspective.finos.org/docs/view.html)
+- Language Guides and API Docs
+ - [Javascript](https://docs.rs/perspective-js/latest/perspective_js/)
+ - [JavaScript (`<perspective-viewer>`) API](https://perspective.finos.org/docs/obj/perspective-viewer/)
+ - [Python](https://docs.rs/perspective-python/latest/perspective_python/)
+ - [Rust](https://docs.rs/perspective-rs/latest/perspective_rs)
+- Appendix
+ - [Data Binding](https://docs.rs/perspective-server/latest/perspective_server/)
  - [Expression Columns](https://perspective.finos.org/docs/expressions.html)
- - [Data Binding](https://perspective.finos.org/docs/table.html)
-- API
- - [Perspective API](https://github.com/finos/perspective/blob/master/packages/perspective/README.md)
- - [Perspective Viewer API](https://perspective.finos.org/docs/obj/perspective-viewer/)
- - [Perspective Python API](https://perspective.finos.org/docs/obj/perspective-python.html)
+ - [Developer Guide](https://perspective.finos.org/docs/development.html)
 
 ### Examples
 
@@ -65,22 +61,19 @@ and/or [Jupyterlab](https://jupyterlab.readthedocs.io/en/stable/).
 <td><a href="https://github.com/timbess"><code>@timbess</code></a></td>
 <td><a href="https://github.com/sc1f"><code>@sc1f</code></a></td>
 </tr>
-<tr><td>
-<a href="https://www.youtube.com/watch?v=s6n9vEyM1gY"><img width="240" src="https://img.youtube.com/vi/s6n9vEyM1gY/0.jpg" /></a>
-</td><td>
-<a href="https://www.youtube.com/watch?v=lDpIu4dnp78"><img width="240" src="https://img.youtube.com/vi/lDpIu4dnp78/0.jpg" /></a>
-</td><td>
-<a href="https://www.youtube.com/watch?v=IO-HJsGdleE"><img width="240" src="https://img.youtube.com/vi/IO-HJsGdleE/0.jpg" /></a>
-</td></tr>
+<tr>
+<td><a href="https://www.youtube.com/watch?v=v5Y5ftlGNhU"><img width="240" src="https://img.youtube.com/vi/v5Y5ftlGNhU/0.jpg" /></a></td>
+<td><a href="https://www.youtube.com/watch?v=lDpIu4dnp78"><img width="240" src="https://img.youtube.com/vi/lDpIu4dnp78/0.jpg" /></a></td>
+<td><a href="https://www.youtube.com/watch?v=0ut-ynvBpGI"><img width="240" src="https://img.youtube.com/vi/0ut-ynvBpGI/0.jpg" /></a></td>
+</tr>
 <tr>
 <td><a href="https://github.com/texodus"><code>@texodus</code></a></td>
 <td><a href="https://github.com/texodus"><code>@texodus</code></a></td>
 <td></td>
 </tr>
-<tr><td>
-<a href="https://www.youtube.com/watch?v=0ut-ynvBpGI"><img width="240" src="https://img.youtube.com/vi/0ut-ynvBpGI/0.jpg" /></a>
-</td><td>
-<a href="https://www.youtube.com/watch?v=no0qChjvdgQ"><img width="240" src="https://img.youtube.com/vi/no0qChjvdgQ/0.jpg" /></a>
-</td><td>
-</td></tr>
+<tr>
+<td><a href="https://www.youtube.com/watch?v=no0qChjvdgQ"><img width="240" src="https://img.youtube.com/vi/no0qChjvdgQ/0.jpg" /></a></td>
+<td><a href="https://www.youtube.com/watch?v=IO-HJsGdleE"><img width="240" src="https://img.youtube.com/vi/IO-HJsGdleE/0.jpg" /></a></td>
+<td></td>
+</tr>
 </tbody></table>

examples/jupyter-notebooks/README.md

@@ -12,4 +12,3 @@ For examples pertaining to `perspective-python` Tornado servers, check out:
 
 - [tornado-python](https://github.com/finos/perspective/tree/master/examples/tornado-python): a simple Tornado server that delivers a static dataset to the user using `perspective-python` and `<perspective-viewer>`.
 - [tornado-streaming-python](https://github.com/finos/perspective/tree/master/examples/tornado-streaming-python): a streaming Tornado server that demonstrates `perspective-python`'s high throughput and performance in streaming scenarios.
-- [workspace-editing-python](https://github.com/finos/perspective/tree/master/examples/workspace-editing-python): a full-featured example using `<perspective-workspace>` that illustrates a deep and powerful integration between `<perspective-workspace>` and `perspective-python`.

rust/perspective-client/docs/client/set_loop_callback.md

@@ -3,5 +3,5 @@ which may be invoked by the Perspective runtime when updates occur. If provided
 a _loop callback_ function via [`Client::set_loop_callback`], such callback
 function invocations be passed to the _loop callback_ instead.
 
-[`Client::set_loop_callback`] can be used to control scheduling/conflation
-(e.g. by adding a delay), as well as executor integration.
+[`Client::set_loop_callback`] can be used to control scheduling/conflation (e.g.
+by adding a delay), as well as executor integration.

docs/docs/expressions.md → rust/perspective-client/docs/expressions.md

@@ -1,28 +1,15 @@
----
-id: expressions
-title: Expression Columns
----
-
-<style>{"#new_column_highlight perspective-viewer {--column-add--border:2px solid red}"}</style>
-
 Perspective supports _expression columns_, which are virtual columns calculated
-as part of the `View`, optionally using values from its underlying `Table`'s
-columns. Such expression columns are defined in Perspective's expression
-language, an extended version of
+as part of the [`crate::View`], optionally using values from its underlying
+[`crate::Table`]'s columns. Such expression columns are defined in Perspective's
+expression language, an extended version of
 [ExprTK](https://github.com/ArashPartow/exprtk), which is itself quite similar
 (in design and features) to expressions in Excel.
 
 ## UI
 
 Expression columns can be created in `<perspective-viewer>` by clicking the "New
-Column" button at the bottom of the column list (in <span
-style={{color:"red"}}>red</span> below), or via the API by adding the expression
-to the `expressions` config key when calling `restore()`.
-
-<div id="new_column_highlight">
-<perspective-viewer></perspective-viewer>
-</div>
-<br/>
+Column" button at the bottom of the column list, or via the API by adding the
+expression to the `expressions` config key when calling `viewer.restore()`.
 
 By default, such expression columns are not "used", and will appear above the
 `Table`'s other deselected columns in the column list, with an additional set of
@@ -36,10 +23,8 @@ buttons for:
  expression column i unused.
 
 To use the column, just drag/select the column as you would a normal column,
-e.g. as a "Filter", "Group By", etc. Expression columns cannot be edited or
-updated (as they exist on the `View()` and are generated from the `Table()`'s
-_real_ columns). However, they will automatically update whenever their
-dependent columns update.
+e.g. as a "Filter", "Group By", etc. Expression columns will recalculate
+whenever their dependent columns update.
 
 ## Perspective Extensions to ExprTK
 
@@ -65,7 +50,7 @@ e.g. `string(x)` to cast a variable `x` to a `string`.
 Expressions can be _named_ by providing a comment as the first line of the
 expression. This name will be used in the `<perspective-viewer>` UI when
 referring to the column, but will also be used in the API when specifying e.g.
-`group_by` or `order_by` fields. When creating a new column via
+`group_by` or `sort` fields. When creating a new column via
 `<oerspective-viewer>`'s expression editor, new columns will get a default name
 (which you may delete or change):
 
@@ -76,29 +61,21 @@ referring to the column, but will also be used in the API when specifying e.g.
 Without such a comment, an expression will show up in the `<perspective-viewer>`
 API and UI as itself (clipped to a reasonable length for the latter).
 
-#### Referencing `Table()` Columns
+#### Referencing [`crate::Table`] Columns
 
-Columns from the `Table()` can be referenced in an expression with _double
-quotes_.
+Columns from the [`crate::Table`] can be referenced in an expression with
+_double quotes_.
 
-```
-// Expected Sales
-("Sales" * 10) + "Profit"
+```text
+// Expected Sales ("Sales" * 10) + "Profit"
 ```
 
-<div>
-<perspective-viewer
- columns='["Sales", "Profit", "Expected Sales"]'
- expressions='{"Expected Sales": "(\"Sales\" * 10) + \"Profit\""}'
-></perspective-viewer>
-</div>
-
 #### String Literals
 
 In contrast to standard ExprTK, string literals are declared with _single
 quotes_:
 
-```
+```text
 // Profitable
 if ("Profit" > 0) {
  'Stonks'
@@ -107,13 +84,6 @@ if ("Profit" > 0) {
 }
 ```
 
-<div>
-<perspective-viewer
- columns='["Profit","Profitable"]'
- expressions='{"Profitable": "if (\"Profit\" > 0) { &apos;Stonks&apos; } else { &apos;Not Stonks&apos; }"}'
-></perspective-viewer>
-</div>
-
 #### Extended Library
 
 Perspective adds many of its own functions in addition to `ExprTK`'s standard
@@ -129,36 +99,20 @@ functions is available in the
 Just `2`, as an `integer` (numeric literals currently default to `float` unless
 cast).
 
-```
+```text
 integer(2)
 ```
 
-<div>
-<perspective-viewer
- columns='["integer(2)"]'
- expressions='["integer(2)"]'
-></perspective-viewer>
-</div>
-<br/>
-
 #### Variables
 
-```
+```text
 // My Column Name
 var incrementedBy200 := "Sales" + 200;
 var half := incrementedBy200 / 2;
 half
 ```
 
-<div>
-<perspective-viewer
- columns='["Sales", "My Column Name"]'
- expressions='{"My Column Name": "var incrementedBy200 := \"Sales\" + 200;\nvar half := incrementedBy200 / 2;\nhalf"}'
-></perspective-viewer>
-</div>
-<br/>
-
-```
+```text
 // Complex Expression
 var upperCustomer := upper("Customer Name");
 var separator := concat(upperCustomer, ' | ');
@@ -168,17 +122,9 @@ var percentDisplay := concat(combined, '%');
 percentDisplay
 ```
 
-<div>
-<perspective-viewer
- columns='["Complex Expression", "Customer Name", "Sales", "Profit"]'
- expressions='{"Complex Expression": "var upperCustomer := upper(\"Customer Name\");\nvar separator := concat(upperCustomer, &apos; | &apos;);\nvar profitRatio := floor(percent_of(\"Profit\", \"Sales\")); // Remove trailing decimal.\nvar combined := concat(separator, string(profitRatio));\nvar percentDisplay := concat(combined, &apos;%&apos;);\npercentDisplay"}'
-></perspective-viewer>
-</div>
-<br/>
-
 #### Conditionals
 
-```
+```text
 // Conditional
 var priceAdjustmentDate := date(2016, 6, 18);
 var finalPrice := "Sales" - "Discount";
@@ -193,10 +139,3 @@ else
 
 finalPrice + additionalModifier
 ```
-
-<div>
-<perspective-viewer
- columns='["Conditional"]'
- expressions='{"Conditional": "var priceAdjustmentDate := date(2016, 6, 18);\nvar finalPrice := \"Sales\" - \"Discount\";\nvar additionalModifier := 0;\n\nif(\"Order Date\" > priceAdjustmentDate) {\n finalPrice -= 5;\n additionalModifier -= 2;\n}\nelse\n finalPrice += 5;\n\nfinalPrice + additionalModifier"}'
-></perspective-viewer>
-</div>