-
Notifications
You must be signed in to change notification settings - Fork 110
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Documentation: Kedro-Viz React component usage #1954
Changes from 11 commits
bae3962
b04bfed
6444897
ac80476
badef39
3f320de
a935cc1
f5e4ab4
0fba958
e49ebc6
083d5a6
1bbe9c5
d8d75ae
f3d2cd8
2215cc1
689d28c
88b516e
18b1c1d
36b10f1
b618de2
e940b21
d8b9043
7764e5f
ab8798e
7d95668
2fe1029
e9f45bd
18e6b1d
0446855
f0a3645
52c7137
8a45d32
f37560e
83bd6f8
b8bb951
939e78d
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,195 @@ | ||
# Kedro-Viz | ||
|
||
<br /> | ||
<p align="center"> | ||
|
||
![Kedro-Viz Pipeline Visualisation](https://raw.githubusercontent.com/kedro-org/kedro-viz/main/.github/img/banner.png) | ||
|
||
</p> | ||
|
||
<p align="center"> | ||
✨ <em> Data Science Pipelines. Beautifully Designed</em> ✨ | ||
Check warning on line 11 in README.npm.md GitHub Actions / vale[vale] README.npm.md#L11
Raw output
|
||
<br /> | ||
Live Demo: <a href="https://demo.kedro.org/" target="_blank">https://demo.kedro.org/</a> | ||
</p> | ||
|
||
<br /> | ||
|
||
[![CircleCI](https://circleci.com/gh/kedro-org/kedro-viz/tree/main.svg?style=shield)](https://circleci.com/gh/kedro-org/kedro-viz/tree/main) | ||
[![Documentation](https://readthedocs.org/projects/kedro/badge/?version=stable)](https://docs.kedro.org/en/stable/visualisation/) | ||
[![Python Version](https://img.shields.io/badge/python-3.9%20%7C%203.10%20%7C%203.11-orange.svg)](https://pypi.org/project/kedro-viz/) | ||
[![PyPI version](https://img.shields.io/pypi/v/kedro-viz.svg?color=yellow)](https://pypi.org/project/kedro-viz/) | ||
[![Downloads](https://static.pepy.tech/badge/kedro-viz/week)](https://pepy.tech/project/kedro-viz) | ||
[![npm version](https://img.shields.io/npm/v/@quantumblack/kedro-viz.svg?color=cc3534)](https://badge.fury.io/js/%40quantumblack%2Fkedro-viz) | ||
Check warning on line 23 in README.npm.md GitHub Actions / vale[vale] README.npm.md#L23
Raw output
|
||
[![License](https://img.shields.io/badge/license-Apache%202.0-3da639.svg)](https://opensource.org/licenses/Apache-2.0) | ||
[![code style: prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg)](https://github.com/prettier/prettier) | ||
[![Slack Organisation](https://img.shields.io/badge/slack-chat-blueviolet.svg?label=Kedro%20Slack&logo=slack)](https://slack.kedro.org) | ||
|
||
## Introduction | ||
|
||
Kedro-Viz is an interactive development tool for building data science pipelines with [Kedro](https://github.com/kedro-org/kedro). Kedro-Viz also allows users to view and compare different runs in the Kedro project. | ||
|
||
## Features | ||
|
||
- ✨ Complete visualisation of a Kedro project and its pipelines | ||
- 🎨 Supports light & dark themes out of the box | ||
- 🚀 Scales to big pipelines with hundreds of nodes | ||
- 🔎 Highly interactive, filterable and searchable | ||
- 🔬 Focus mode for modular pipeline visualisation | ||
- 📊 Rich metadata side panel to display parameters, plots, etc. | ||
Check warning on line 39 in README.npm.md GitHub Actions / vale[vale] README.npm.md#L39
Raw output
|
||
jitu5 marked this conversation as resolved.
Show resolved
Hide resolved
|
||
- 📊 Supports all types of [Plotly charts](https://plotly.com/javascript/) | ||
- ♻️ Autoreload on code change | ||
Check warning on line 41 in README.npm.md GitHub Actions / vale[vale] README.npm.md#L41
Raw output
|
||
- 🧪 Supports tracking and comparing runs in a Kedro project | ||
- 🎩 Many more to come | ||
Check warning on line 43 in README.npm.md GitHub Actions / vale[vale] README.npm.md#L43
Raw output
|
||
|
||
## Installation | ||
|
||
- As a standalone React component (for embedding Kedro-Viz in your web application). | ||
|
||
To install the standalone React component: | ||
|
||
```bash | ||
npm install @quantumblack/kedro-viz | ||
``` | ||
|
||
## Usage | ||
|
||
To use Kedro-Viz as a standalone React component, you can follow the example below. Please note that Kedro-Viz does not support server-side rendering (SSR). If you are using Next.js or another SSR framework, you should be aware of this limitation. | ||
|
||
```javascript | ||
import KedroViz from '@quantumblack/kedro-viz'; | ||
import '@quantumblack/kedro-viz/lib/styles/styles.min.css'; | ||
|
||
const MyApp = () => <KedroViz data={json} />; | ||
``` | ||
|
||
To use with NextJS: | ||
|
||
```javascript | ||
import '@quantumblack/kedro-viz/lib/styles/styles.min.css'; | ||
import dynamic from 'next/dynamic'; | ||
|
||
const NoSSRKedro = dynamic(() => import('@quantumblack/kedro-viz'), { | ||
ssr: false, | ||
}); | ||
|
||
const MyApp = () => <NoSSRKedro data={json} />; | ||
``` | ||
|
||
The JSON can be obtained by running: | ||
|
||
```bash | ||
kedro viz run --save-file=<path-to-save-kedro-viz-data-to-a-directory> | ||
``` | ||
|
||
On successful execution of the command above, it will generate a folder at the specified directory, containing the following structure: | ||
|
||
``` | ||
<filename>/api/ | ||
├── main | ||
├── nodes | ||
│ ├── 23c94afb | ||
│ ├── 28754fab | ||
│ ├── 2ab3579f | ||
│ ├── 329e963c | ||
│ ├── 369acf98 | ||
│ └── ... | ||
└── pipelines | ||
├── __default__ | ||
├── data_processing | ||
├── data_science | ||
└── ... | ||
``` | ||
|
||
Please use the `main` file as the input JSON for the `data` prop in your Kedro-Viz component. | ||
jitu5 marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
We also recommend wrapping the `Kedro-Viz` component with a parent HTML/JSX element that has a specified height (as seen in the above example) in order for Kedro-Viz to be styled properly. | ||
Check notice on line 106 in README.npm.md GitHub Actions / vale[vale] README.npm.md#L106
Raw output
|
||
jitu5 marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
**_Our documentation contains [additional examples on how to visualise with Kedro-Viz.](https://docs.kedro.org/en/stable/visualisation/index.html)_** | ||
|
||
## Props | ||
|
||
Below is the example with all possible props. | ||
jitu5 marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
``` | ||
<KedroViz | ||
data={json} | ||
display={{ | ||
globalToolbar: false, | ||
miniMap: false, | ||
expandAllPipelines: false, | ||
}} | ||
visible={{ | ||
labelBtn: false, | ||
layerBtn: false, | ||
exportBtn: false, | ||
pipelineBtn: false, | ||
sidebar: false, | ||
}} | ||
theme="dark" | ||
/> | ||
``` | ||
|
||
| Name | Type | Default | Description | | ||
| ------------ | ------- | ------- | ----------- | | ||
| `data` | `{ edges: array (required), layers: array, nodes: array (required), tags: array }` | - | Pipeline data will be displayed on the chart | | ||
jitu5 marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| `theme` | string | dark | select Kedro-Viz theme dark/light | | ||
| display | | | | | ||
| `globalToolbar` | boolean | true | If `false` Global sidebar on extreme left will be hidden | | ||
Check warning on line 138 in README.npm.md GitHub Actions / vale[vale] README.npm.md#L138
Raw output
|
||
jitu5 marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| `miniMap` | boolean | true | If `false` miniMap button at the bottom of the primaryToolbar will be hidden | | ||
Check warning on line 139 in README.npm.md GitHub Actions / vale[vale] README.npm.md#L139
Raw output
Check warning on line 139 in README.npm.md GitHub Actions / vale[vale] README.npm.md#L139
Raw output
Check warning on line 139 in README.npm.md GitHub Actions / vale[vale] README.npm.md#L139
Raw output
|
||
| `expandAllPipelines` | boolean | false | If `true` all modular pipelines on first load will be expanded | | ||
Check warning on line 140 in README.npm.md GitHub Actions / vale[vale] README.npm.md#L140
Raw output
|
||
| visible | | | | | ||
| `labelBtn` | boolean | true | If `false` labelBtn button at the top of the primaryToolbar will be hidden | | ||
Check warning on line 142 in README.npm.md GitHub Actions / vale[vale] README.npm.md#L142
Raw output
Check warning on line 142 in README.npm.md GitHub Actions / vale[vale] README.npm.md#L142
Raw output
Check warning on line 142 in README.npm.md GitHub Actions / vale[vale] README.npm.md#L142
Raw output
|
||
| `layerBtn` | boolean | true | If `false` layerBtn button at the top of the primaryToolbar will be hidden | | ||
Check warning on line 143 in README.npm.md GitHub Actions / vale[vale] README.npm.md#L143
Raw output
Check warning on line 143 in README.npm.md GitHub Actions / vale[vale] README.npm.md#L143
Raw output
Check warning on line 143 in README.npm.md GitHub Actions / vale[vale] README.npm.md#L143
Raw output
|
||
| `exportBtn` | boolean | true | If `false` exportBtn button at the top of the primaryToolbar will be hidden | | ||
Check warning on line 144 in README.npm.md GitHub Actions / vale[vale] README.npm.md#L144
Raw output
Check warning on line 144 in README.npm.md GitHub Actions / vale[vale] README.npm.md#L144
Raw output
Check warning on line 144 in README.npm.md GitHub Actions / vale[vale] README.npm.md#L144
Raw output
|
||
| `pipelineBtn` | boolean | true | If `false` pipelineBtn button at the top of the primaryToolbar will be hidden | | ||
Check warning on line 145 in README.npm.md GitHub Actions / vale[vale] README.npm.md#L145
Raw output
Check warning on line 145 in README.npm.md GitHub Actions / vale[vale] README.npm.md#L145
Raw output
Check warning on line 145 in README.npm.md GitHub Actions / vale[vale] README.npm.md#L145
Raw output
|
||
| `sidebar` | boolean | true | If `false` sidebar on left will be minimized | | ||
Check warning on line 146 in README.npm.md GitHub Actions / vale[vale] README.npm.md#L146
Raw output
Check warning on line 146 in README.npm.md GitHub Actions / vale[vale] README.npm.md#L146
Raw output
|
||
|
||
All components are annotated to understand their positions in the Kedro-Viz UI. | ||
|
||
![Kedro-Viz component annotation](https://raw.githubusercontent.com/jitu5/kedro-viz/main/.github/img/kedro-viz-annotation.png) | ||
|
||
|
||
## Standalone Example Repository | ||
Check warning on line 153 in README.npm.md GitHub Actions / vale[vale] README.npm.md#L153
Raw output
|
||
|
||
We have created a [kedro-viz-standalone](https://github.com/kedro-org/kedro-viz-standalone.git) repository to demonstrate how to use Kedro-Viz in standalone mode or embedded in a React application. | ||
Check warning on line 155 in README.npm.md GitHub Actions / vale[vale] README.npm.md#L155
Raw output
|
||
|
||
This repository provides a fully functional example of Kedro-Viz, showcasing how to integrate it into your projects. The example includes setup instructions and demonstrates various features of Kedro-Viz. | ||
|
||
To get started, clone the repository, install the dependencies and run the example React application: | ||
|
||
``` | ||
git clone https://github.com/kedro-org/kedro-viz-standalone.git | ||
cd kedro-viz-standalone | ||
npm install | ||
npm start | ||
``` | ||
|
||
## Feature Flags | ||
Check warning on line 168 in README.npm.md GitHub Actions / vale[vale] README.npm.md#L168
Raw output
|
||
|
||
Kedro-Viz uses feature flags to roll out some experimental features. We have the following flags - | ||
|
||
| Flag | Description | | ||
| ------------------ | --------------------------------------------------------------------------------------- | | ||
| sizewarning | From release v3.9.1. Show a warning before rendering very large graphs (default `true`) | | ||
Check warning on line 174 in README.npm.md GitHub Actions / vale[vale] README.npm.md#L174
Raw output
Check warning on line 174 in README.npm.md GitHub Actions / vale[vale] README.npm.md#L174
Raw output
Check warning on line 174 in README.npm.md GitHub Actions / vale[vale] README.npm.md#L174
Raw output
|
||
| expandAllPipelines | From release v4.3.2. Expand all modular pipelines on first load (default `false`) | | ||
|
||
To enable or disable a flag, click on the settings icon in the toolbar and toggle the flag on/off. | ||
|
||
Kedro-Viz also logs a message in your browser's [developer console](https://developer.mozilla.org/en-US/docs/Learn/Common_questions/What_are_browser_developer_tools#The_JavaScript_console) to show the available flags and their values as currently set on your machine. | ||
Check warning on line 179 in README.npm.md GitHub Actions / vale[vale] README.npm.md#L179
Raw output
|
||
|
||
## Maintainers | ||
|
||
Kedro-Viz is maintained by the [Kedro team](https://docs.kedro.org/en/stable/contribution/technical_steering_committee.html#kedro-maintainers) and a number of [contributors from across the world](https://github.com/kedro-org/Kedro-Viz/contributors). | ||
Check warning on line 183 in README.npm.md GitHub Actions / vale[vale] README.npm.md#L183
Raw output
Check warning on line 183 in README.npm.md GitHub Actions / vale[vale] README.npm.md#L183
Raw output
|
||
|
||
## Contribution | ||
|
||
If you want to contribute to Kedro-Viz, please check out our [contributing guide](./CONTRIBUTING.md). | ||
Check warning on line 187 in README.npm.md GitHub Actions / vale[vale] README.npm.md#L187
Raw output
|
||
|
||
## License | ||
|
||
Kedro-Viz is licensed under the [Apache 2.0](https://github.com/kedro-org/kedro-viz/blob/main/LICENSE.md) License. | ||
|
||
## Citation | ||
|
||
If you're an academic, Kedro-Viz can also help you, for example, as a tool to visualise how your publication's pipeline is structured. Find our citation reference on [Zenodo](https://doi.org/10.5281/zenodo.4277218). | ||
Check warning on line 195 in README.npm.md GitHub Actions / vale[vale] README.npm.md#L195
Raw output
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Nice!