Skip to content

Commit

Permalink
Update demos and contributing (#548)
Browse files Browse the repository at this point in the history 
* Remove deprecated Bio.Alphabet module

* Added assets, updated layout_helper import, and fixed dcc.Loading css

* Remove common directory and update requirements

* Adding back common directory

* Remove unnecessary gallery scripts and add common template

* Updated CONTRIBUTING and CHANGELOG

* Add extract-meta

* Linting

* Update CONTRIBUTING.md

Co-authored-by: Alex Johnson <[email protected]>

Co-authored-by: Alex Johnson <[email protected]>
  • Loading branch information
@HammadTheOne @alexcjohnson
HammadTheOne and alexcjohnson authored Apr 19, 2021
1 parent ab64f01 commit 4d3fb48
Show file tree
Hide file tree
Showing 135 changed files with 12,377 additions and 614 deletions.
1 change: 0 additions & 1 deletion .buildpacks
View file

This file was deleted.

4 changes: 4 additions & 0 deletions CHANGELOG.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,10 @@
* [#554](https://github.com/plotly/dash-bio/pull/554) Added additional props and arbitrary layout arguments to VolcanoPlot.


### Fixed
- [#550](https://github.com/plotly/dash-bio/pull/548) Updated CONTRIBUTING.md andbasic demo app structure. In addition, removed residual code and pre-deploy scripts associated with now-discontinued Dash Bio gallery.


## [0.6.1] - 2021-02-15
### Fixed
* [#544](https://github.com/plotly/dash-bio/pull/544) Miscellaneous fixes for NglMoleculeViewer component.
Expand Down
190 changes: 94 additions & 96 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
## Development
# Development

#### Prerequisites
### Prerequisites

- [Git](https://git-scm.com/)
- [node.js](https://nodejs.org/en/). We recommend using node.js v10.x, but all
Expand All @@ -17,93 +17,101 @@
client
([setup instructions](http://faculty.smu.edu/reynolds/unixtut/windows.html)).

#### Step 1: Clone the dash-bio repo and install its dependencies
## Step 1: Clone the dash-bio repo and install its dependencies

```bash
git clone https://github.com/plotly/dash-bio.git
cd dash-bio
npm ci
```

#### Step 2: Develop
## Step 2: Develop

Development of a component for this repository comprises two parts:
Development of a component for this repository is composed of two parts:
the component itself, and a sample application that showcases the capabilities
of your component and how it interacts with Dash.

##### Components
### Components
Components can either be created using React, or they can be written
in pure Python. React components are written in `src/lib/components`
before being compiled into Python components that are in the
`dash_bio` folder. Python components are written in
`dash_bio/component_factory/` and must be imported in
`dash_bio/__init__.py`.

##### Installing new npm packages
### Installing new npm packages

If developing a new component based on a React library, please ensure
that you have already installed the correct versions of the
preexisting dependencies by running `npm ci`. Then, add the package to
pre-existing dependencies by running `npm ci`. Then, add the package to
`package.json` and run `npm i` to add it to the `package-lock.json` file.

###### Naming components
### Naming components
Components, regardless of whether they are written using React or
Python, need to be named in upper camel case. This is incredibly
important due to the amount of parsing we perform in our testing suite
and app deployments.

##### Demo applications
Instead of creating standalone Dash apps for each component, there is a file
structure in place to create a main "gallery" page that contains links to each
(component) application. Consequently, the implementation of a component needs
to follow a specific file structure for the corresponding app to be displayed
and run correctly.

###### Setup
In the `tests/dashbio_demos/` subfolder, please create a file named
`app_{your component name in snake case}.py`. In this file, please include the
following functions:

* `layout()` should return whatever you would have in your `app.layout`. Due to
the way the CSS is set up for each application, it is advisable to create a
container `div` that will house your application, e.g.,
```python
def layout():
return html.Div(id='my-component-container', children=[
"A sample component",
dash_bio.MyComponent(id='my-component'),
html.Div(id='my-component-output'),
])
```
* `callbacks(app)` should contain all of the callbacks in the application and
not return anything, e.g.,
```python
def callbacks(app):
@app.callback(
Output('my-component-output', 'children'),
[Input('my-component', 'someProperty')]
)
def update_output(property):
return "Value: {}".format(str(property))
```

###### Testing
### Demo applications
Dash Bio demo apps follow a standardized template and showcase the properties
of the component and possible use-cases with sample datasets. The `assets` and
`layout_helper.py` modules in the `common` subdirectory include the base CSS styling for
demo apps and helper functions to generate the layout and callback structure to run
the demo as a standalone Dash app. These should be added to your demo app directory
to ensure that the layout and structure of your app is consistent when deployed
to the Dash Gallery. See *Setup* below for more details on using `layout_helper.py`
within your demo application.

### Setup
In the `tests/dashbio_demos/common` subdirectory, you will find the minimal project structure for a Dash Bio demo app. This includes the following files:

* `app.py`: This contains your Python app code with the demo component. The `app.py` in this case contains a basic outline of the code required for a Dash Bio sample app, but it can be modified or replaced as necessary for a particular component or demo app. If you are using this template, please note the following:
>* `layout()` should return whatever you would have in your `app.layout`. Due to
>the way the CSS is set up for each application, it is advisable to create a
>container `div` that will house your application, e.g.,
>```python
>def layout():
> return html.Div(id='my-component-container', children=[
> "A sample component",
> dash_bio.MyComponent(id='my-component'),
> html.Div(id='my-component-output'),
> ])
>```
>* `callbacks(app)` should contain all of the callbacks in the application and
>not return anything, e.g.,
>```python
>def callbacks(app):
> @app.callback(
> Output('my-component-output', 'children'),
> [Input('my-component', 'someProperty')]
> )
> def update_output(property):
> return "Value: {}".format(str(property))
>```
* `requirements.txt`: A text file which includes all the Python dependencies that need to be installed in order to run the app.
* `layout_helper.py`: A Python module with helper functions to generate the template app layout and callback structure for a Dash Bio gallery app.
* `data`: A directory that can contain sample datasets.
* `assets`: A directory which can contain custom CSS, JS, favicon, or styling assets. Dash will automatically serve all of the files that are included in this folder.
* `Procfile`: Procfile is a required text file that declares which commands should be run by the server on startup like starting your app's web server, scheduling jobs and running background processes. For Dash Bio demo apps, it can remain unmodified.
### Testing
Test out your application by going to the repository's root directory and
running
```bash
python index.py
python tests/dashbio_demos/{YOUR_DEMO_APP}/app.py
```
Then navigate to `localhost:8050` in your web browser. You should see the
gallery page. To get to your application, click on the square that displays the
name of your component upon hover.
Then navigate to `localhost:8050` in your web browser.

You will need to quit the Python application and rerun it if you have made
changes to the Python file itself, or have recently rebuilt/reinstalled the
Dash Bio package. To see updated CSS changes, you can simply reload the webpage
in your browser.
in your browser, or enable hot-reloading with [Dash Dev Tools](https://dash.plotly.com/devtools).

###### CSS
### CSS
All custom CSS stylesheets should go in the `assets/` folder. Please create a
stylesheet with a filename specific to your component. In addition, all ids and
class names in your application should be prefixed by the name of your
Expand All @@ -115,39 +123,39 @@ if you want to make a container `div` for your application as mentioned in the
Setup subsection, please account for an extra height of `100px` that is taken
up by the header when you are specifying the height of the container.

###### Final touches
### Final touches
In the `tests/dashbio_demos/images/` subfolder, please include a PNG file named
`pic_{your component name in snake case}.png`.

In your demo app file, please include the following functions:
* `description()` is responsible for the text that shows up on hovering over
>* `description()` is responsible for the text that shows up on hovering over
your application in the gallery page. It should return a short string with a
description of the component, e.g.,
```python
def description():
return "Display bioinformatics data with this component."
```
* `header_colors()` controls the appearance of the header for your application.
>```python
>def description():
> return "Display bioinformatics data with this component."
>```
>* `header_colors()` controls the appearance of the header for your application.
It should return a dictionary with any or all of the specified keys `bg_color`
(string), `font_color` (string), and `light_logo` (boolean). Please change the
background color from default, and try to choose one that isn't used for
another application, e.g.,
```python
def header_colors():
return {
'bg_color': 'rgb(255, 0, 0)',
'font_color': 'rgb(255, 255, 255)',
'light_logo': True
}
```
>```python
>def header_colors():
> return {
> 'bg_color': 'rgb(255, 0, 0)',
> 'font_color': 'rgb(255, 255, 255)',
> 'light_logo': True
> }
>```
Please lint any additions to Python code with `pylint` and/or `flake8`.
Commit each changeset corresponding to a conceptual entity.
Write commit messages at the imperative (e.g., "Document workflow").
Each commit is small; a pull request typically consists of a few commits.
#### Step 3: Run tests locally
## Step 3: Run tests locally
To run integration tests locally on, say, Google Chrome:
```bash
Expand All @@ -160,7 +168,7 @@ pytest tests/integration #for testing all apps
pytest tests/integration/test_yourNewApp #for testing only one app
```
Do not worry if you get errors running this last command. You will have to
download a Chrome driver (Linux:chromium), install it, and add its path.
download a Chrome driver (Linux:chromium), install it, and add it to your PATH.
Follow what the error messages point to (this will be platform-specific).
To write more integration tests, please read this
Expand All @@ -173,26 +181,27 @@ python tests/unit/unit_test_data_setup.py
npm run test
```
#### Step 4: Rebuild the package if necessary
## Step 4: Rebuild the package if necessary
If you have made changes to the JS code, then you need to rebuild the package:
```bash
npm run build
npm run build:all
```
The auto-generated Python files will reflect your updates to the logic.
If, instead, you have made changes to the layout, you do not need to rebuild
the package.
#### Step 5: Submit a pull request (PR)
## Step 5: Submit a pull request (PR)
Fill out the description template in the GitHub interface.
When you submit the PR, a Heroku review app will be automatically created; it
will remain available for 5 days.
Fill out the description template in the GitHub interface. Please include a
link to the original JavaScript component if your PR is porting a React component
to Dash Bio, and any relevant details or sample datasets that might help with
testing the component and demo app.
### Deployment
## Deployment
*Deployment is done from the `master` branch only.*
Expand All @@ -207,39 +216,28 @@ remote add [app name]-test [deployment server git URL]`.
#### Step 2: Edit and commit app-specific files
##### Step 2a: Edit the `Procfile`
Edit the `Procfile` at the root of the repository to say `gunicorn
tests.dashbio_demos.app_name:server`, where `app_name` is the name of
the app you want to deploy in the `tests/dashbio_demos/` folder.

##### Step 2b: Edit `config.py`
Edit the `config.py` file at the root of the repository such that the variable
`DASH_APP_NAME` be set to the name of your app, but with `app`
replaced by `dash` and underscores (`_`) replaced by dashes
(`-`). (e.g., for `app_manhattan_plot`, the `DASH_APP_NAME` variable
should be set to `dash-manhattan-plot`.)

##### Step 2c: Commit the changes
Commit the `Procfile` and `config.py`, but *do not push to the
`dash-bio` repo*!
>#### Step 2a: Edit the `Procfile`
>Edit the `Procfile` at the root of the repository to say `web: gunicorn app:server`.
>
>#### Step 2b: Commit the changes
>Commit the `Procfile` and other changes, but *do not push to the
`dash-bio` repo* !
#### Step 3: Push to the playground server
Run `git push [app name]-test master`. This will deploy the app
on the playground server. Check that it works by visiting the URL that
is displayed in the console. Try out a few of the callbacks to make
Run `git subtree push --prefix tests/dashbio_demos/[app directory] [app name]-test master`. This will deploy the app on the playground server. Check that it works by visiting the URL that is displayed in the console. Try out a few of the callbacks to make
sure that they are working.
#### Step 4: Initialize the app on the dash-gallery server and push to it
Log into the `developers` account on
[dash-gallery.plotly.host](dash-gallery.plotly.host) and follow the same
instructions as in Step 1, but give this remote a different name
(e.g., by running `git remote add gallery [deployment server git
URL]`). Then, run `git push gallery master`.
(e.g. by running `git remote add gallery [deployment server git
URL]`). Then, run `git subtree push --prefix tests/dashbio_demos/[app directory] gallery master`.
#### Step 5: Undo the app-specific commit
Run `git log` to find the ID of the commit prior to the one that you
just made to change the `Procfile`. Then, reset your local branch to
this commit so that the `index.py` app still deploys and runs
this commit so that the `app.py` app still deploys and runs
normally. You can do this by running `git reset --hard [commit ID]`.
#### Step 6: Ensure that your branch is even with `master`
Expand Down
2 changes: 0 additions & 2 deletions Procfile
View file

This file was deleted.

21 changes: 0 additions & 21 deletions app.json
View file

This file was deleted.

Loading

0 comments on commit 4d3fb48

Please sign in to comment.