Skip to content

Latest commit

 

History

History
64 lines (46 loc) · 5.32 KB

DEVELOPER-GUIDE.md

File metadata and controls

64 lines (46 loc) · 5.32 KB

Developer Guide

Finish reading this guide before you start working on a PR.

Setup

The recommended setup for developing WaloViz requires to install 2 things:

  1. VSCode
  2. Docker Desktop

Clone the repository in your favorite manner, and open it with VSCode.
Now follow these steps:

  1. Install the Dev Containers extension
  2. Reopen folder in Dev Container (ctrl+shift+P -> type "Reopen", this may take a few minutes)
  3. git checkout develop

Where is Stuff?

The Repository Structure is like so:

  1. src/ - the waloviz package itself, it contains its minimum src/requirements.txt
  2. doc/ - the templates for the Documentation Website, it contains doc/requirements.txt which are specific for the docs
  3. tests/ - the manual and UI tests, it contains tests/requirements.txt which are specific for the tests
  4. .devcontainer/ - configuration for the VSCode DevContainer extension, it contains .devcontainer/requirements.txt which are specific for development
  5. requirements.txt - points to all of the previously mentioned */requirements.txt
  6. pyproject.toml - the pypi package configuration
  7. examples/ - notebooks for the docs

Technologies

In this repo there are many technologies for many reasons.
YOU DON'T NEED TO KNOW ALL OF THEM TO MAKE A PR!
Most issues have a "Recommended Knowledge" section, all you need to know is listed there. If you need more background on how a specific technology fits in to WaloViz, then this is the section for you.

Here is a non-comprehensive list which explains each technology with helpful links:

  • Github Actions - A versatile CI\CD solution with a huge community, for automated CI\CD pipelines
  • Github Pages - A simple static hosting solution, for hosting the Test Documentation Website
  • Read the Docs - An E2E documentation hosting solution, for hosting our Released Documentation Websites
  • VSCode Dev Containers - A Docker based local development environment, for easy on-boarding and development setup
  • pre-commit - a framework for managing pre-commit hooks. In our repo it does mainly static typing, linting and reformatting with Pyright, Ruff, Prettier and the built-in pre-commit-hooks.
  • NBSite - a Sphinx wrapper for HoloViz websites, generates our Documentation Website
  • Jupyter - a notebook format for interactive python, popular amongst Data-Scientists and researchers in general. Popular IDEs are Jupyter Notebook, JupyterLab, VSCode and Google Colab. Almost all users of WaloViz use it in Jupyter notebooks with one of the mentioned IDEs.
  • Bokeh - A low level interactive plotting framework, it supports Jupyter notebooks. The spectrograms, axes, toolbar and progress bar of the WaloViz player are all native Bokeh components. Bokeh allows advanced JS linking and customizations which WaloViz uses extensively.
  • HoloViews - Part of the HoloViz ecosystem. A high level interactive plotting API, can use Bokeh, Plotly or Matplotlib as backends, it supports Jupyter notebooks. WaloViz uses HoloViews to create the basic structure of the player, and uses Bokeh for the final customizations.
  • Panel - Part of the HoloViz ecosystem. A widget based web app framework for creating interactive applications and dashboards, it supports Jupyter notebooks. WaloViz uses Panel for the audio player, the download button, HTML exporting and responsiveness.
  • PyTorch - An accelerated tensor based framework for Deep-Learning and Data-Science. WaloViz uses PyTorch tensors as the basic format for the audio and spectrogram data.
  • TorchAudio - Part of the PyTorch ecosystem. TorchAudio has many domains specific features for audio research. WaloViz uses TorchAudio to load audio files into PyTorch tensors and to generate the spectrogram.
  • PyTest - A python testing framework
  • Playwright - A browser simulator, used for testing UI components of WaloViz
  • hatchling - A modern python package builder, we use it with hatch-vcs for easy git tag based releases.

Did you read the entire guide?

No

🆙 Back to the top with you 🆙

YES

You Are READY.
What a wonder you are, a truly Certified Contributor, thank you :)