Skip to content

Commit 87874b6

Browse files
author
Xing Han Lu
authored
Merge pull request #660 from plotly/update-readme
Refactor Readme and add a contributing doc Former-commit-id: 2bed4b3
2 parents 433d65b + c897390 commit 87874b6

File tree

2 files changed

+193
-185
lines changed

2 files changed

+193
-185
lines changed

‎CONTRIBUTING.md‎

Lines changed: 183 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,183 @@
1+
# CONTRIBUTING
2+
3+
## Running an example app after cloning the repo
4+
5+
You will need to run applications, and specify filenames, from the
6+
root directory of the repository. e.g., if the name of the app you
7+
want to run is `my_dash_app` and the app filename is `app.py`, you
8+
would need to run `python apps/my_dash_app/app.py` from the root
9+
of the repository.
10+
11+
Each app has a requirements.txt, install the dependencies in a virtual
12+
environment.
13+
14+
15+
## Contributing to the sample apps repo
16+
17+
_"DDS app" below refers to the deployed application. For example, if
18+
the deployment will eventually be hosted at
19+
https://dash-gallery.plotly.host/my-dash-app, "DDS app name" is
20+
`my-dash-app`._
21+
22+
### Adding a new app
23+
24+
Create an app on Dash Playground. This will be the location of the
25+
auto-deployment. To do this, log into the app manager on
26+
[dash-playground.plotly.host](https://dash-playground.plotly.host)
27+
and click "initialize app".
28+
29+
Create a branch from `master` to work on your app, the name is not required
30+
to be anything specific. Switch to this branch, then navigate to the `apps/`
31+
directory and add a directory for your app.
32+
33+
There are two options when you are naming the folder:
34+
35+
1. Make the folder have the _exact same_ name as the Dash app name.
36+
37+
2. (Python apps only) Select any other name, but _update the file
38+
[`apps_mapping.py`](apps_directory_mapping.py)_ with the Dash app
39+
name and the folder name you have selected.
40+
41+
Navigate to the directory you just created, and write a small README
42+
that only contains the name of the app. Stage the README and commit it
43+
to your branch.
44+
45+
See [project boilerplate!](https://github.com/plotly/dash-sample-apps#project-boilerplate)
46+
47+
### Notes on adding a new Dash for R app
48+
49+
Contributing an app written with Dash for R is very similar to the steps outlined above.
50+
51+
1. Make the folder have the _exact same_ name as the Dash app name.
52+
53+
2. Ensure that the file containing your app code is named `app.R`.
54+
55+
3. The `Procfile` should contain
56+
57+
```
58+
web: R -f /app/app.R
59+
```
60+
61+
4. Routing and request pathname prefixes should be set. One approach might be to include
62+
63+
```
64+
appName <- Sys.getenv("DASH_APP_NAME")
65+
pathPrefix <- sprintf("/%s/", appName)
66+
67+
Sys.setenv(DASH_ROUTES_PATHNAME_PREFIX = pathPrefix,
68+
DASH_REQUESTS_PATHNAME_PREFIX = pathPrefix)
69+
```
70+
71+
at the head of your `app.R` file.
72+
73+
5. `run_server()` should be provided the host and port information explicitly, e.g.
74+
75+
``
76+
app$run_server(host = "0.0.0.0", port = Sys.getenv('PORT', 8050))
77+
``
78+
79+
### Making changes to an existing app
80+
81+
Create a new branch - of any name - for your code changes.
82+
Then, navigate to the directory that has the same name as
83+
the DDS app.
84+
85+
When you are finished, make a pull request from your branch to the master
86+
branch. Once you have passed your code review, you can merge your PR.
87+
88+
## Dash app project structure
89+
90+
#### Data
91+
- All data (csv, json, txt, etc) should be in a data folder
92+
- `/apps/{DASH_APP_NAME}/data/`
93+
94+
#### Assets
95+
- All stylesheets and javascript should be in an assets folder
96+
- `/apps/{DASH_APP_NAME}/assets/`
97+
98+
#### These files will still need to be present within the app folder.
99+
100+
- **`Procfile`** gets run at root level for deployment
101+
- Make sure python working directory is at the app level
102+
- Ex. `web: gunicorn app:server`
103+
- **`requirements.txt`**
104+
- Install project dependecies in a virtual environment
105+
106+
#### Project boilerplate
107+
108+
apps
109+
├── ...
110+
├── {DASH_APP_NAME} # app project level
111+
│ ├── assets/ # all stylesheets and javascript files
112+
│ ├── data/ # all data (csv, json, txt, etc)
113+
│ ├── app.py # dash application entry point
114+
│ ├── Procfile # used for heroku deployment (how to run app)
115+
│ ├── requirements.txt # project dependecies
116+
│ └── ...
117+
└── ...
118+
119+
#### Handle relative path
120+
121+
Assets should never use a relative path, as this will fail when deployed to Dash Enterprise due to use of subdirectories for serving apps.
122+
123+
Reading from assets and data folder
124+
```Python
125+
Img(src="./assets/logo.png") will fail at root level
126+
```
127+
128+
Tips
129+
130+
- Use [get_asset_url()](https://dash.plot.ly/dash-deployment-server/static-assets)
131+
- Use [Pathlib](https://docs.python.org/3/library/pathlib.html) for more flexibility
132+
133+
```Python
134+
import pathlib
135+
import pandas as pd
136+
137+
# get relative assets
138+
html.Img(src=app.get_asset_url('logo.png')) # /assets/logo.png
139+
140+
# get relative data
141+
142+
DATA_PATH = pathlib.Path(__file__).parent.joinpath("data") # /data
143+
df = pd.read_csv(DATA_PATH.joinpath("sample-data.csv")) # /data/sample-data.csv
144+
145+
with open(DATA_PATH.joinpath("sample-data.csv")) as f: # /data/sample-data.csv
146+
some_string = f.read()
147+
```
148+
149+
## Developer Guide
150+
151+
#### Creating a new project
152+
153+
```
154+
# branch off master
155+
git checkout -b "{YOUR_CUSTOM_BRANCH}"
156+
157+
# create a new folder in apps/
158+
mkdir /apps/{DASH_APP_NAME}
159+
160+
# push new branch
161+
git push -u origin {YOUR_CUSTOM_BRANCH}
162+
```
163+
164+
#### Before committing
165+
166+
```
167+
# make sure your code is linted (we use black)
168+
black . --exclude=venv/ --check
169+
170+
# if black is not installed
171+
pip install black
172+
```
173+
174+
175+
#### App is ready to go!
176+
```
177+
# once your branch is ready, make a PR into master!
178+
179+
PR has two checkers.
180+
1. make sure your code passed the black linter
181+
2. make sure your project is deployed on dns playground
182+
```
183+

‎README.md‎

Lines changed: 10 additions & 185 deletions
Original file line numberDiff line numberDiff line change
@@ -1,28 +1,10 @@
1-
# Dash Sample Apps [![CircleCI](https://circleci.com/gh/plotly/dash-sample-apps.svg?style=svg)](https://circleci.com/gh/plotly/dash-sample-apps)
1+
# Dash Sample Apps
22

3-
This monorepo contains open-source apps demoing
4-
various capabilities of Dash and integration with
5-
the Python or R ecosystem. Most of the apps here
6-
are hosted on the
7-
[Dash Gallery](https://dash-gallery.plotly.host/Portal/),
8-
which runs on the
9-
[Dash Kubernetes](https://plotly.com/dash/kubernetes/) platform
10-
and host both open-source apps and demos for
11-
[Design Kit](https://plotly.com/dash/design-kit/) and
12-
[Snapshot Engine](https://plotly.com/dash/snapshot-engine/). Reach
13-
out to [get a demo](https://plotly.com/get-demo/) of our licensed
14-
products.
3+
[![CircleCI](https://circleci.com/gh/plotly/dash-sample-apps.svg?style=svg)](https://circleci.com/gh/plotly/dash-sample-apps)
154

16-
## Running an example app after cloning the repo
5+
This repository hosts the code for over 100 open-source Dash apps written in Python or R. They can serve as a starting point for your own Dash app, as a learning tool to better understand how Dash works, as a reusable templates, and much more.
176

18-
You will need to run applications, and specify filenames, from the
19-
root directory of the repository. e.g., if the name of the app you
20-
want to run is `my_dash_app` and the app filename is `app.py`, you
21-
would need to run `python apps/my_dash_app/app.py` from the root
22-
of the repository.
23-
24-
Each app has a requirements.txt, install the dependencies in a virtual
25-
environment.
7+
Most apps in this repository are hosted on [Dash Gallery](https://dash-gallery.plotly.host/), which is our internal server running on [Dash Enterprise Kubernetes](https://plotly.com/dash/kubernetes/). Note that you can find both open-sourced apps and demos for our [licensed products](https://plotly.com/dash/), including [Design Kit](https://plotly.com/dash/design-kit/) and [Snapshot Engine](https://plotly.com/dash/snapshot-engine/). If you are interested in learning more, don't hesitate to reach out to [get a demo](https://plotly.com/get-demo/). If you want to only see the open-sourced apps, select the ["Open Source" tag](https://dash-gallery.plotly.host/Portal/?search=[Open%20Source]).
268

279
## Downloading and running a single app
2810

@@ -39,172 +21,15 @@ then run the app:
3921
python app.py
4022
```
4123

42-
## Contributing to the sample apps repo
43-
44-
_"DDS app" below refers to the deployed application. For example, if
45-
the deployment will eventually be hosted at
46-
https://dash-gallery.plotly.host/my-dash-app, "DDS app name" is
47-
`my-dash-app`._
48-
49-
### Adding a new app
50-
51-
Create an app on Dash Playground. This will be the location of the
52-
auto-deployment. To do this, log into the app manager on
53-
[dash-playground.plotly.host](https://dash-playground.plotly.host)
54-
and click "initialize app".
55-
56-
Create a branch from `master` to work on your app, the name is not required
57-
to be anything specific. Switch to this branch, then navigate to the `apps/`
58-
directory and add a directory for your app.
59-
60-
There are two options when you are naming the folder:
61-
62-
1. Make the folder have the _exact same_ name as the Dash app name.
63-
64-
2. (Python apps only) Select any other name, but _update the file
65-
[`apps_mapping.py`](apps_directory_mapping.py)_ with the Dash app
66-
name and the folder name you have selected.
67-
68-
Navigate to the directory you just created, and write a small README
69-
that only contains the name of the app. Stage the README and commit it
70-
to your branch.
71-
72-
See [project boilerplate!](https://github.com/plotly/dash-sample-apps#project-boilerplate)
73-
74-
### Notes on adding a new Dash for R app
75-
76-
Contributing an app written with Dash for R is very similar to the steps outlined above.
77-
78-
1. Make the folder have the _exact same_ name as the Dash app name.
79-
80-
2. Ensure that the file containing your app code is named `app.R`.
81-
82-
3. The `Procfile` should contain
83-
84-
```
85-
web: R -f /app/app.R
86-
```
87-
88-
4. Routing and request pathname prefixes should be set. One approach might be to include
24+
## Cloning this whole repository
8925

26+
To clone this repository, run:
9027
```
91-
appName <- Sys.getenv("DASH_APP_NAME")
92-
pathPrefix <- sprintf("/%s/", appName)
93-
94-
Sys.setenv(DASH_ROUTES_PATHNAME_PREFIX = pathPrefix,
95-
DASH_REQUESTS_PATHNAME_PREFIX = pathPrefix)
28+
git clone https://github.com/plotly/dash-sample-apps
9629
```
9730

98-
at the head of your `app.R` file.
99-
100-
5. `run_server()` should be provided the host and port information explicitly, e.g.
101-
102-
``
103-
app$run_server(host = "0.0.0.0", port = Sys.getenv('PORT', 8050))
104-
``
105-
106-
### Making changes to an existing app
107-
108-
Create a new branch - of any name - for your code changes.
109-
Then, navigate to the directory that has the same name as
110-
the DDS app.
111-
112-
When you are finished, make a pull request from your branch to the master
113-
branch. Once you have passed your code review, you can merge your PR.
114-
115-
## Dash app project structure
116-
117-
#### Data
118-
- All data (csv, json, txt, etc) should be in a data folder
119-
- `/apps/{DASH_APP_NAME}/data/`
120-
121-
#### Assets
122-
- All stylesheets and javascript should be in an assets folder
123-
- `/apps/{DASH_APP_NAME}/assets/`
124-
125-
#### These files will still need to be present within the app folder.
126-
127-
- **`Procfile`** gets run at root level for deployment
128-
- Make sure python working directory is at the app level
129-
- Ex. `web: gunicorn app:server`
130-
- **`requirements.txt`**
131-
- Install project dependecies in a virtual environment
31+
Note this might take a long time since it copies over 100 apps available in the repo. If you just want to try one app, refer to the section above.
13232

133-
#### Project boilerplate
134-
135-
apps
136-
├── ...
137-
├── {DASH_APP_NAME} # app project level
138-
│ ├── assets/ # all stylesheets and javascript files
139-
│ ├── data/ # all data (csv, json, txt, etc)
140-
│ ├── app.py # dash application entry point
141-
│ ├── Procfile # used for heroku deployment (how to run app)
142-
│ ├── requirements.txt # project dependecies
143-
│ └── ...
144-
└── ...
145-
146-
#### Handle relative path
147-
148-
Assets should never use a relative path, as this will fail when deployed to Dash Enterprise due to use of subdirectories for serving apps.
149-
150-
Reading from assets and data folder
151-
```Python
152-
Img(src="./assets/logo.png") will fail at root level
153-
```
154-
155-
Tips
156-
157-
- Use [get_asset_url()](https://dash.plot.ly/dash-deployment-server/static-assets)
158-
- Use [Pathlib](https://docs.python.org/3/library/pathlib.html) for more flexibility
159-
160-
```Python
161-
import pathlib
162-
import pandas as pd
163-
164-
# get relative assets
165-
html.Img(src=app.get_asset_url('logo.png')) # /assets/logo.png
166-
167-
# get relative data
168-
169-
DATA_PATH = pathlib.Path(__file__).parent.joinpath("data") # /data
170-
df = pd.read_csv(DATA_PATH.joinpath("sample-data.csv")) # /data/sample-data.csv
171-
172-
with open(DATA_PATH.joinpath("sample-data.csv")) as f: # /data/sample-data.csv
173-
some_string = f.read()
174-
```
175-
176-
## Developer Guide
177-
178-
#### Creating a new project
179-
180-
```
181-
# branch off master
182-
git checkout -b "{YOUR_CUSTOM_BRANCH}"
183-
184-
# create a new folder in apps/
185-
mkdir /apps/{DASH_APP_NAME}
186-
187-
# push new branch
188-
git push -u origin {YOUR_CUSTOM_BRANCH}
189-
```
190-
191-
#### Before committing
192-
193-
```
194-
# make sure your code is linted (we use black)
195-
black . --exclude=venv/ --check
196-
197-
# if black is not installed
198-
pip install black
199-
```
200-
201-
202-
#### App is ready to go!
203-
```
204-
# once your branch is ready, make a PR into master!
205-
206-
PR has two checkers.
207-
1. make sure your code passed the black linter
208-
2. make sure your project is deployed on dns playground
209-
```
33+
## Contributing
21034

35+
To contribute to this repository, please see the [contributing guide](CONTRIBUTING.md).

0 commit comments

Comments
 (0)