docs: improve contributing.md and some minor improvements (#41)

.github/workflows/pr-title.yml

@@ -11,7 +11,7 @@ jobs:
     steps:
       - uses: deepakputhraya/action-pr-title@master
         with:
-          regex: "^(add:|build:|ci:|docs:|feat:|fix:|bug:|perf:|refactor:|revert:|style:|test:|security:).{12,60}$"
+          regex: "^(add:|build:|ci:|docs:|feat:|fix:|maintain:|bug:|perf:|refactor:|revert:|style:|test:|security:).{12,60}$"
           min_length: 10
           max_length: 60
           github_token: "${{ secrets.GITHUB_TOKEN }}"

.github/workflows/release.yml

@@ -14,4 +14,4 @@ jobs:
           prerelease: true
           default-branch: main
           pull-request-header: ":robot: I have created a release *beep* *boop*. This was predictable."
-          changelog-types: '[{"type":"resolve","section":"Miscellaneous","hidden":true},{"type":"add","section":"Features","hidden":false},{"type":"feat","section":"Features","hidden":false},{"type":"fix","section":"Bug Fixes","hidden":false},{"type":"bug","section":"Bug Fixes","hidden":false},{"type":"chore","section":"Miscellaneous","hidden":true},{"type":"test","section":"Tests","hidden":false},{"type":"ci","section":"CI/CD","hidden":false},{"type":"refactor","section":"Maintenance","hidden":false},{"type":"perf","section":"Maintenance","hidden":false},{"type":"revert","section":"Maintenance","hidden":true},{"type":"docs","section":"Documentation","hidden":false},{"type":"security","section":"Security","hidden":false}]'
+          changelog-types: '[{"type":"maintain","section":"Maintenance","hidden":false},{"type":"resolve","section":"Miscellaneous","hidden":true},{"type":"add","section":"Features","hidden":false},{"type":"feat","section":"Features","hidden":false},{"type":"fix","section":"Bug Fixes","hidden":false},{"type":"bug","section":"Bug Fixes","hidden":false},{"type":"chore","section":"Miscellaneous","hidden":true},{"type":"test","section":"Tests","hidden":false},{"type":"ci","section":"CI/CD","hidden":false},{"type":"refactor","section":"Maintenance","hidden":false},{"type":"perf","section":"Maintenance","hidden":false},{"type":"revert","section":"Maintenance","hidden":true},{"type":"docs","section":"Documentation","hidden":false},{"type":"security","section":"Security","hidden":false}]'

.gitignore

@@ -131,4 +131,4 @@ dmypy.json
 
 # Custom
 .DS_Store
-/models
+codecov

.pre-commit-config.yaml

@@ -13,6 +13,7 @@ repos:
             "ci",
             "docs",
             "feat",
+            "bug",
             "fix",
             "refactor",
             "revert",
@@ -21,6 +22,7 @@ repos:
             "perf",
             "resolve",
             "merge",
+            "maintain",
           ]
 
   - repo: https://github.com/pre-commit/pre-commit-hooks
@@ -41,6 +43,11 @@ repos:
       - id: fix-byte-order-marker
       - id: forbid-new-submodules
 
+  - repo: https://github.com/bwhmather/ssort
+    rev: v0.11.6
+    hooks:
+      - id: ssort
+
   - repo: https://github.com/asottile/pyupgrade
     rev: v3.3.1
     hooks:

.vscode/settings.json

@@ -4,4 +4,7 @@
     ],
     "python.testing.unittestEnabled": false,
     "python.testing.pytestEnabled": true,
+    "cSpell.words": [
+        "blitzly"
+    ],
 }

CODE_OF_CONDUCT.md

@@ -56,6 +56,16 @@ Examples of representing our community include using an official e-mail address,
 posting via an official social media account, or acting as an appointed
 representative at an online or offline event.
 
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+[christopher.lemke@invia.de](mailto:christopher.lemke@invia.de).
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
 ## Enforcement Guidelines
 
 Community leaders will follow these Community Impact Guidelines in determining

docs/CONTRIBUTING.md

@@ -1,5 +1,7 @@
 # How to contribute
 
+Thank 🙏 you for your interest in contributing to this project! Please read this document to get started.
+
 ## Poetry
 We are using [Poetry](https://python-poetry.org/) to manage the dependencies, for deployment, and the virtual environment. If you have not used it before please check out the [documentation](https://python-poetry.org/docs/) to get started.
 
@@ -16,7 +18,7 @@ pre-commit install --hook-type commit-msg
 ```
 
 ## Homebrew
-We are using [Homebrew](https://brew.sh/) to manage the dependencies for the development environment. Please install Homebrew and run
+We are using [Homebrew](https://brew.sh/) to manage the dependencies for the development environment. Please install Homebrew and run:
 ```bash
  brew bundle
 ```
@@ -27,10 +29,9 @@ We are using [Conventional Commits](https://www.conventionalcommits.org) to ensu
 ```bash
 <type>[optional scope]: <description>
 ```
-
 E.g.:
 ```bash
-feat: add a new fantastic plot 📈
+feat: new fantastic plot 📈
 ```
 
 ## How to contribute
@@ -42,7 +43,7 @@ The following steps will give a short guide on how to contribute to this project
 - If you created your fork a while ago be sure to pull upstream changes into your local repository.
 - Create a new branch to work on! Start from `develop` if it exists, else from `main`.
 - Implement/fix your feature, comment your code, and add some examples.
-- Follow the code style of the project, including indentation. [Black](https://github.com/psf/black), [isort](https://github.com/PyCQA/isort), [Pylint](https://github.com/PyCQA/pylint), and [mypy](https://github.com/python/mypy) can help you with it.
+- Follow the code style of the project, including indentation. [Black](https://github.com/psf/black), [isort](https://github.com/PyCQA/isort), [Pylint](https://github.com/PyCQA/pylint), [mypy](https://github.com/python/mypy), and [ssort](https://github.com/bwhmather/ssort) can help you with it.
 - Run all tests.
 - Write or adapt tests as needed.
 - Add or change the documentation as needed. Please follow the "[Google Python Style Guide](https://google.github.io/styleguide/pyguide.html)".
@@ -51,3 +52,131 @@ The following steps will give a short guide on how to contribute to this project
 - From your fork open a pull request in the correct branch. Target the project's `develop` branch!
 - Once the pull request is approved and merged you can pull the changes from `upstream` to your local repo and delete
 your extra branch(es).
+
+## Example
+This is a simple example of a possible implementation of a new function:
+```python
+def simple_dumbbell(
+    data: Union[pd.DataFrame, NDArray],
+    title: str = "Dumbbell plot",
+    marker_size: int = 16,
+    marker_line_width: int = 8,
+    plotly_kwargs: Optional[dict] = None,
+    size: Optional[Tuple[int, int]] = None,
+    show_legend: Optional[bool] = None,
+    show: bool = True,
+    write_html_path: Optional[str] = None,
+) -> BaseFigure:
+
+    """
+    Creates a dumbbell plot. These are useful to show the difference between
+    two sets of data which have the same categories. For instance, it can be
+    used to compare two binary classifiers by plotting the various classification
+    metrics.
+
+    Example:
+    ```python
+    from blitzly.plots.dumbbell import simple_dumbbell
+    import numpy as np
+    import pandas as pd
+
+    data = {
+        "foo": np.random.randn(10),
+        "bar": np.random.randn(10),
+    }
+    index = [f"category_{i+1}" for i in range(10)]
+    df = pd.DataFrame(data, index=index)
+
+    simple_dumbbell(df)
+    ```
+
+    Args:
+        data (Union[pd.DataFrame, NDArray]): Data to plot.
+        title (str): Title of the plot.
+        marker_size (int): Size of the circular marker of the dumbbells.
+        marker_line_width (int): Thickness of the line joining the markers.
+        plotly_kwargs (Optional[dict]): Additional keyword arguments to pass to Plotly `go.Scatter`.
+        size (Optional[Tuple[int, int]): Size of the plot.
+        show_legend (Optional[bool]): Whether to show the legend.
+        show (bool): Whether to show the figure.
+        write_html_path (Optional[str]): The path to which the histogram should be written as an HTML file.
+            If None, the histogram will not be saved.
+
+    Returns:
+        BaseFigure: The dumbbell plot.
+    """
+
+    data = check_data(data, min_rows=1, min_columns=2, max_columns=2, as_pandas=True)
+
+    fig = go.Figure()
+
+    for index, row in data.iterrows():
+        fig.add_trace(
+            go.Scatter(
+                x=[row.iloc[0], row.iloc[1]],
+                y=[index, index],
+                mode="lines",
+                showlegend=False,
+                line={
+                    "color": "black",
+                    "width": marker_line_width,
+                },
+            )
+        )
+
+    for column_idx, column_name in enumerate(data.columns):
+        fig.add_trace(
+            go.Scatter(
+                x=data.iloc[:, column_idx],
+                y=data.index,
+                mode="markers",
+                name=column_name,
+                **plotly_kwargs if plotly_kwargs else {},
+            )
+        )
+
+    fig.update_traces(
+        marker=dict(size=marker_size),
+    )
+
+    fig = update_figure_layout(fig, title, size, show_legend)
+    return save_show_return(fig, write_html_path, show)
+```
+
+Let's go through the code step by step:
+1. To make blitzly ⚡️ simple to use try to provide as many default arguments as possible. Also don't forget to add type hints:
+    ```python
+    title: str = "Dumbbell plot"
+    ```
+    **Yea!** 🥳
+
+    ```python
+    title
+    ```
+    **Nay!** 😢
+
+2. Every function in blitzly ⚡️ requires the following arguments:
+    ```python
+    plotly_kwargs: Optional[dict] = None,
+    show: bool = True,
+    write_html_path: Optional[str] = None
+    ```
+    More about this in the next steps.
+
+3. Each function should return `BaseFigure`. This gives the user the possibility to use the returned Plotly figure in every possible way.
+
+4. The function should have a docstring. The docstring should follow the [Google Python Style Guide](https://google.github.io/styleguide/pyguide.html). The docstring should contain a short description of the function, a short example, a list of all arguments, and a description of the return value.
+
+5. [`check_data`](https://invia-flights.github.io/blitzly/utils/#blitzly.etc.utils.check_data) is used for validating and preparing the data for the plot. Please don't forget to add it to your implementation.
+
+6. So no code is repeated we use [`update_figure_layout`](https://invia-flights.github.io/blitzly/utils/#blitzly.etc.utils.update_figure_layout) to update the layout of the figure.
+
+7. [`save_show_return`](https://invia-flights.github.io/blitzly/utils/#blitzly.etc.utils.save_show_return) is used to save the figure as an HTML file - if needed, shows the figure, and returns the figure. The use of this function is also mandatory.
+
+8. When you work on the implementation try to make the implementation as generic as possible. In other words, try to wrap a powerful Plotly implementation in your blitzly function and pass as many arguments as possible to the user while giving default arguments. In addition to this please also provide a `plotly_kwargs` argument which allows the user to pass additional keyword arguments to the Plotly function. This way the user can customize the plot as much as possible.
+
+9. Don't forget to write some meaningful unit tests. The tests should cover all possible use cases of the function and should be located in the `tests/test_cases` folder and should be named `test_<function_name_with_use_case>.py`.
+
+10. Documentation: Please add your new blitly ⚡️ plot to the list in the [`README.md`](https://github.com/invia-flights/blitzly#available-plots-so-far-) file. If you think your plot implementation is worth to be documented even more, feel free to add it together with a short description to the end of the [`playground.ipynb`](https://github.com/invia-flights/blitzly/blob/main/examples/playground.ipynb) notebook.
+
+That's it! 🎉 Happy ploding (plotting + coding)! 📊👩‍💻 If you have any questions feel free to contact us!

docs/README.md

@@ -5,6 +5,7 @@
 [![DeployPackage](https://github.com/invia-flights/blitzly/actions/workflows/deploy-package.yml/badge.svg)](https://github.com/invia-flights/blitzly/actions/workflows/deploy-package.yml)
 [![Testing](https://github.com/invia-flights/blitzly/actions/workflows/testing.yml/badge.svg?branch=main)](https://github.com/invia-flights/blitzly/actions/workflows/testing.yml)
 [![codecov](https://codecov.io/gh/invia-flights/blitzly/branch/develop/graph/badge.svg?token=ROCDJJV8JV)](https://codecov.io/gh/invia-flights/blitzly)
+[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/invia-flights/blitzly/blob/main/examples/playground.ipynb)
 [![pypi](https://img.shields.io/pypi/v/blitzly)](https://pypi.org/project/blitzly/)
 [![PyPI - Downloads](https://img.shields.io/pypi/dm/blitzly)](https://pypistats.org/packages/blitzly)
 [![python version](https://img.shields.io/pypi/pyversions/blitzly?logo=python&logoColor=yellow)](https://www.python.org/downloads/)
@@ -18,7 +19,7 @@
 ## Introduction 🎉
 Plotly is great and powerful. But with great power comes great responsibility 🕸. And sometimes you just want to get a plot up and running as fast as possible. That's where blitzly ⚡️ comes in. It provides a set of functions that allow you to create plots with Plotly in a lightning-fast way. It's not meant to replace Plotly, but rather to complement it.
 
-Check out some examples in the [Jupyter notebook](https://github.com/invia-flights/blitzly/blob/main/examples/playground.ipynb):<br>
+Check out some examples in the [Jupyter notebook](https://github.com/invia-flights/blitzly/blob/main/examples/playground.ipynb).<br>
 [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/invia-flights/blitzly/blob/main/examples/playground.ipynb)
 
 ## Install the package 📦

examples/playground.ipynb

@@ -210,7 +210,7 @@
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "blitzly",
+   "display_name": "plotly",
    "language": "python",
    "name": "python3"
   },
@@ -228,7 +228,7 @@
   },
   "vscode": {
    "interpreter": {
-    "hash": "f4fa492d61aa4bd4bbaeb19b5818168dde89106ff3309a91e7db70fcb63410b9"
+    "hash": "797bdba0bac3be9cd36b18a3613c96bf1dbb820419cf6fd1cafb2b83e9b9f245"
    }
   }
  },