Skip to content

Latest commit

 

History

History
126 lines (106 loc) · 6.14 KB

README.md

File metadata and controls

126 lines (106 loc) · 6.14 KB

PyPI version npm version Build Status Total alerts Language grade: JavaScript Language grade: Python Python 3.6 | 3.7 | 3.8 | 3.9 Code style: black code style: prettier codecov

Webviz subsurface components

webviz_subsurface_components is a Dash/React component library for use in webviz, which have in common that they are geared towards subsurface dashboards. There is an online demo available at https://equinor.github.io/webviz-subsurface-components/.

How to install the components

You can quickly get started using the components in Dash by:

  1. Run pip install webviz-subsurface-components
  2. Run python examples/example_hm.py
  3. Visit http://localhost:8050 in your web browser

This project was originally generated by the dash-component-boilerplate. (with some modifications).

If you are only interested in using the JavaScript code in your own JavaScript project, you can install the npmjs deployed version:

npm i @webviz/subsurface-components

How to contribute

Install dependencies

If you want to build and develop yourself, you should fork + clone the repository, and then:

  1. Install npm packages
    npm ci --ignore-scripts --prefix ./react
    
  2. Run some potentially optional postinstall scripts
    npm run setup_deckgl_types --prefix ./react  # only needed if ignored scripts during install
    npm run copy-package-json --prefix ./react  # only needed if building Dash components
    
  3. Install python packages required to build components.
    pip install .[dependencies]
    pip install dash[dev]
    
  4. Install the python packages for testing.
    pip install .[tests]
    pip install dash[testing]
    
    The second of these commands appears to be necessary as long as this pip issue is open.

Write component code in src/lib/components/<component_name>/<component_name>.jsx

  • The demo app is in src/demo and is where you will import an example of your component. To start the existing demo app, run npm start.

  • To test your code in a Python environment:

    1. Build your code
      npm run build:all --prefix ./react
      
    2. Install the Python pacakge in development mode (if not already done and assuming you are using a virtual environment):
      pip install -e .
      
    3. Create a new example in examples/ which uses your new component.
  • Write tests for your component.

    • Tests exist in tests/. Take a look at them to see how to write tests using the Dash test framework.
    • Run the tests with pytest tests.
  • Add custom styles to your component by putting your custom CSS files into your distribution folder (webviz_subsurface_components).

    • Make sure that they are referenced in MANIFEST.in so that they get properly included when you're ready to publish your component.
    • Make sure the stylesheets are added to the _css_dist dict in webviz_subsurface_components/__init__.py so dash will serve them automatically when the component suite is requested.
  • Every file related to the component should be located in the component directory, unless the file is shared between multiple components. Only the component you want to export as a Dash-component should have the .jsx-extension, the rest of the sub-components should have .js. For example the file-structure should look something like this:

src
|--lib
    |----<component_name>
        |----components
              |----<sub_component>.js
        |----utils
        |----<component_name>.jsx
        |----<component_name>.css
        |----index.js

Automatically upload demo application

This repository has a GitHub workflow which can automatically build and deploy a demo app with your changes, to GitHub pages.

  • On push to your feature branch, in your fork, the workflow will build and deploy a demo app to your fork's GitHub page, given that your commit message includes the substring [deploy test].
  • On merge to master in the main repository, a build + deploy will be done to the official GitHub page in the main repository.

For this to work in your own fork, you will need to create a branch gh-pages (this you only need to do once). One way of creating this branch is e.g.:

git checkout --orphan gh-pages
git rm -rf .
git commit --allow-empty -m  "Create GitHub pages branch"
git push origin gh-pages

You are encouraged to rebase and squash/fixup unnecessary commits before pull request is merged to master.