init doc

README.md

@@ -1,22 +1,32 @@
-# pfund-plot
+# PFund-Plot
 
-A high-level out-of-the-box, domain-specific plotting library for **financial data visualization designed for traders**.
+[![Twitter Follow](https://img.shields.io/twitter/follow/pfund_ai?style=social)](https://x.com/pfund_ai)
+![GitHub stars](https://img.shields.io/github/stars/PFund-Software-Ltd/pfund-plot?style=social)
+[![Jupyter Notebook](https://img.shields.io/badge/jupyter-notebook-orange?logo=jupyter)](https://jupyter.org)
+[![Marimo](https://marimo.io/shield.svg)](https://marimo.io)
+![PyPI downloads](https://img.shields.io/pypi/dm/pfund-plot?label=downloads)
+[![PyPI](https://img.shields.io/pypi/v/pfund-plot.svg)](https://pypi.org/project/pfund-plot)
+![PyPI - Support Python Versions](https://img.shields.io/pypi/pyversions/pfund-plot)
 
+## Problem
+Traders often need to quickly visualize their data without investing time in learning new tools.
+For example, plotting an orderbook should be as simple as writing a single line of code.
 
-> This library is not ready, please wait for version 0.0.1 release.
-
+## Solution
+We created a high-level plotting library that combines the best features from existing plotting and dashboarding libraries into an easy-to-use interface.
 
-## Why pfund-plot?
-This library is designed for traders who just want to get their data visualized and displayed in the simplest way possible, 
-there is almost no learning curve.
+---
+PFund-Plot is a super high-level, out-of-the-box, domain-specific plotting library designed for traders that supports **financial data visualization**, **dashboard creation**, and **template sharing**.
 
+> This library is not ready, please wait for version 0.0.1 release.
 
 ## Core Features
 - [x] Multi-Display Mode: support displaying plots in a *Jupyter notebook*, *Marimo notebook*, *browser* and *desktop window*
 - [x] Streaming Data: support streaming data in real-time by just setting `streaming=True`
 - [x] DataFrame Agnostic: support pandas, polars, and dask
-- [x] Financial Plots: e.g. candlestick, orderbook, trades etc.
-
+- [x] Big Data Plotting: support plotting large datasets
+- [x] Financial Plots: plot financial data by just one function call, e.g. candlestick, orderbook, trades etc.
+- [x] Combine multiple plots into a dashboard quickly for visualization
 
 
 ## Installation

docs/CONTRIBUTING.md

@@ -0,0 +1,91 @@
+[hvplot]: https://hvplot.holoviz.org/
+[holoviews]: https://holoviews.org/
+[panel]: https://panel.holoviz.org/
+[plotly]: https://plotly.com/
+[altair]: https://altair-viz.github.io/
+[narwhals]: https://github.com/narwhals-dev/narwhals
+
+
+# CONTRIBUTING
+
+Thank you for your interest in contributing to PFund-Plot! This guide will help you get started.
+
+
+## Development Setup
+```bash
+git clone https://github.com/PFund-Software-Ltd/pfund-plot.git
+cd pfund-plot
+poetry install --with dev,test --all-extras
+```
+
+
+## Adding a new plot
+1. if the plot is supported by [hvplot], use hvplot to implement the plot
+2. if the plot is not supported by hvplot, use [holoviews] to implement the plot
+3. if holoviews doesn't support the plot, use [panel] to implement the plot
+
+> Panel can be used as the standardized interface for different plotting libraries.
+
+e.g. if you want to use `plotly`
+```python
+import panel as pn
+import plotly.graph_objects as go
+from pfund_plot.renderer import render
+
+# your plotly figure
+fig = go.Figure(...)
+
+# convert plotly figure to panel
+panel_fig = pn.pane.Plotly(fig)
+
+# pass the panel figure to the render function
+render(panel_fig)
+```
+
+e.g. if you want to use `altair`
+```python
+import panel as pn
+import altair as alt
+from pfund_plot.renderer import render
+
+# your altair figure
+fig = alt.Chart(...)
+
+# convert altair figure to panel
+panel_fig = pn.pane.Vega(fig)
+
+# pass the panel figure to the render function
+render(panel_fig)
+```
+
+The same logic can be applied to other plotting libraries as long as `panel` supports them.
+e.g. there are also `pn.pane.Bokeh`, `pn.pane.Matplotlib`, `pn.pane.ECharts`, `pn.pane.HoloViews`, etc.
+
+
+## Dataframe Manipulation
+`pfund-plot` supports `pandas`, `polars` and `dask` dataframes. If you need to manipulate the input dataframe, please use the [narwhals] library.
+
+
+## Example
+Your function will look something like this:
+```python
+# tDataFrame is just a type alias for pandas, polars and dask dataframes
+from pfeed.types.core import tDataFrame
+from typing import Literal
+from pfund_plot.renderer import render
+
+
+def your_plot(
+    data: tDataFrame,
+    streaming: bool = False,
+    display_mode: Literal['notebook', 'browser', 'desktop'] = "notebook",
+    raw_figure: bool = False,  # add this if your function uses hvplot
+):
+    # your plotting logic
+    ...
+    return render(panel_fig)
+```
+
+For a full example, see the function `candlestick_plot()` in `pfund_plot/plots/candlestick.py`.
+It is a standard way to make a plot using hvplot, and pn.state.add_periodic_callback() to make the plot streaming.
+

docs/README.md

@@ -0,0 +1,15 @@
+# Notes on using `myst` to execute ipynb files
+
+`myst start`: reads the outputs (if any) of ipynb files but won't execute them.
+
+`myst start --execute`: reads the outputs from _build/execute, if not exist, it will execute the ipynb files and create the outputs.
+
+If you want to rebuild the ipynb outputs, you need to run `myst clean --execute` to delete the _build/execute folder, then run `myst start --execute` again.
+
+---
+
+The same logic applies to `myst build`.
+1. `myst clean --execute` (if needed, for a clean build, run `myst clean` to clear cache)
+2. `myst build --execute --html`
+3. `npx serve _build/html`
+

docs/build.sh

@@ -0,0 +1,26 @@
+#!/bin/bash
+
+# write the GA_TRACKING_ID (secret already set on github) to the myst.yml file
+CONFIG_PATH="docs/myst.yml"
+if [[ "$OSTYPE" == "darwin"* ]]; then  # sed in macos is different
+  sed -i '' "s/GA_TRACKING_ID_PLACEHOLDER/$GA_TRACKING_ID/" $CONFIG_PATH
+else
+  sed -i "s/GA_TRACKING_ID_PLACEHOLDER/$GA_TRACKING_ID/" $CONFIG_PATH
+fi
+
+# install python dependencies so that jupyter notebooks can be executed
+pip install jupyter-book "pfund-plot[all]"
+
+# Clear Cache, Build HTML Assets and Execute Notebooks
+cd docs/
+myst clean --all --yes
+
+# somehow --execute in myst doesn't work, use "jupyter nbconvert" instead to execute notebooks
+# myst build --html --execute
+
+# clear outputs in notebooks
+# find . -path './_build' -prune -o -name '*.ipynb' -print -exec jupyter nbconvert --ClearOutputPreprocessor.enabled=True --inplace {} \;
+# execute notebooks
+# find . -path './_build' -prune -o -name '*.ipynb' -print -exec jupyter nbconvert --execute --inplace {} \;
+
+myst build --html

docs/cli_commands.md

@@ -0,0 +1,39 @@
+# CLI Commands
+
+## Plotting
+```bash
+# TODO: plot sth using command `pfplt`
+```
+
+
+## Configuration
+```bash
+# list current configs
+pfplt config --list
+
+# for more config options, run:
+pfplt config --help 
+```
+
+
+## Open Configuration Files
+For convenience, you can open the config files directly from your CLI.
+```bash
+# open the config file with VS Code/Cursor AI
+pfplt open --config-file
+```
+
+## Start/Build Docs
+> need to have `mystmd` installed to start/build docs locally: `npm install -g mystmd`
+```bash
+# open the docs in browser
+pfplt doc
+# --execute: execute the jupyter notebooks
+pfplt doc --start [--execute]
+pfplt doc --build [--execute]
+```
+
+## Open Terminal UI
+```bash
+pfplt tui
+```

docs/getting-started/getting-started.md

@@ -0,0 +1,23 @@
+[hvplot]: https://hvplot.holoviz.org/
+[panel]: https://panel.holoviz.org/
+[bokeh]: https://bokeh.org/
+[Tabulator]: https://panel.holoviz.org/reference/widgets/Tabulator.html
+[Perspective]: https://panel.holoviz.org/reference/panes/Perspective.html
+
+# Getting Started
+
+::::{grid} 1 1 2 3
+
+:::{card}
+:link: candlestick
+:header: Candlestick
+Candlestick plot using [bokeh] with [hvplot]
+:::
+
+:::{card}
+:link: dataframe
+:header: Dataframe
+Dataframe plot using [Tabulator] or [Perspective] with [panel]
+:::
+
+::::

docs/getting-started/installation.md

@@ -0,0 +1,18 @@
+# Installation
+
+[![Twitter Follow](https://img.shields.io/twitter/follow/pfund_ai?style=social)](https://x.com/pfund_ai)
+![GitHub stars](https://img.shields.io/github/stars/PFund-Software-Ltd/pfund-plot?style=social)
+[![Jupyter Notebook](https://img.shields.io/badge/jupyter-notebook-orange?logo=jupyter)](https://jupyter.org)
+[![marimo](https://marimo.io/shield.svg)](https://marimo.io)
+![PyPI downloads](https://img.shields.io/pypi/dm/pfund-plot)
+[![PyPI](https://img.shields.io/pypi/v/pfund-plot.svg)](https://pypi.org/project/pfund-plot)
+![PyPI - Support Python Versions](https://img.shields.io/pypi/pyversions/pfund-plot)
+
+
+```bash
+# Core Features, no dashboard sharing
+pip install -U "pfund-plot"
+
+# or, pick your own dashboard backend, e.g.
+pip install -U "pfund-plot[streamlit, dash, taipy, gradio, solara]"
+```