Merge pull request #3 from highcharts-for-python/develop

PR for v.1.0.0

Author: hcpchris

CODE_OF_CONDUCT.md

@@ -0,0 +1,46 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at [email protected]. The project team will review and investigate all complaints, and will respond in a way that it deems appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, available at [http://contributor-covenant.org/version/1/4][version]
+
+[homepage]: http://contributor-covenant.org
+[version]: http://contributor-covenant.org/version/1/4/

HISTORY.rst

@@ -0,0 +1,14 @@
+Release 1.0.0-rc2
+=========================================
+
+* Added additional demos for Highcharts Stock for Python.
+* Added additional demos for Highcharts Maps for Python.
+* Added additional demos for Highcharts Gantt for Python.
+* Updated README.
+
+----------
+
+Release 1.0.0-rc1
+=========================================
+
+* Preliminary set of demos, linked to a MyBinder.org binder.

LICENSE

@@ -1,57 +1,168 @@
 # Highcharts for Python Demos
-This is a collection of demonstrations of the Highcharts for Python toolkit.
-Fundamentally, they are a Python port of the fantastic demos that Highsoft has
-already published for their 
-[Highcharts JavaScript library](https://www.highcharts.com/demo).
+This is a collection of demonstrations of the Highcharts for Python toolkit. Fundamentally, they are a Python port of the fantastic demos that Highsoft has already published for their [Highcharts JavaScript library](https://www.highcharts.com/demo).
+
+## Overview
+
+The demos showcase a variety of ways of working with Highcharts for Python to create and visualize data. Because Highcharts for Python provides multiple paths to create your visualizations, we have tried to showcase various methods. Some demos use:
+
+  * **Direct instantiation**. They create Python instances of objects using Python constructors like ``LineSeries(...)`` directly.
+  * ``.from_js_literal()``. They create ``HighchartsOptions`` instances by taking a string of a JS literal option configuration using the ``.from_js_literal()`` method.
+  * ``.from_dict()``. They create Python instances using the Highcharts for Python ``.from_dict()`` convenience method.
+  * other demo-specific techniques, which may vary from demo to demo
+
+Each demo ultimately demonstrates one or more visualizations using one of the techniques mentioned above. The basic pattern we use is to:
+
+  1. Import the needed dependencies.
+  2. Assemble the options.
+  3. Assemble the chart.
+  4. Visualize the chart.
+
+**NOTE!! The demos in this repository are a work in progress, and various demos will be added over time. Please check back periodically to see if new demos have been added.**
 
 ## How to Use the Demos
-First, clone this Github repo:
 
-```
-$ git clone [email protected]:highcharts-for-python/highcharts-for-python-demos.git
-```
+### Organization
+The demos are organized in Jupyter Notebooks, which make it easy to follow how they work, see their results in action, and experiment with them as needed.
+
+The repository is organized into folders for each of the Highcharts for Python libraries:
+
+  * ``highcharts-core`` contains demos of the [Highcharts Core for Python](https://core-docs.highchartspython.com) library
+  * ``highcharts-stock`` contains demos of the [Highcharts Stock for Python](https://stock-docs.highchartspython.com) library
+  * ``highcharts-maps`` contains demos of the [Highcharts Maps for Python](https://maps-docs.highchartspython.com) library
+  * ``highcharts-gantt`` contains demos of the [Highcharts Gantt for Python](https://gantt-docs.highchartspython.com) library
+
+Within each of these folders, you will find sub-folders grouping demos into a particular category. For example:
+
+  * the ``highcharts-core/line-charts`` folder contains Jupyter Notebooks which demonstrate different line chart functionality. 
+  * the ``highcharts-core/python-features`` folder contains Notebooks which demonstrate some Python-specific features
+
+### Using the Demos via MyBinder.org
+
+The easy way to use or review the demos is to launch a MyBinder session using the following buttton: [![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/highcharts-for-python/highcharts-for-python-demos/HEAD)
+
+Once the MyBinder launches, you will find yourself in a Jupyter Lab environment within a Docker image. You'll have this full repository available to you, and you can navigate the folders to find the demo you want to run. 
+
+For example, to see how **Highcharts Core for Python** generates a basic line chart, you can open the Notebook at ``highcharts-core/line-charts/basic-line.ipynb``.
+
+Then just run the Notebook, and you should see the results.
+
+### Using the Demos Locally
+To use the demos locally, you need to take several additional steps:
+
+1. First, clone this Github repo:
+
+    ```
+    $ git clone [email protected]:highcharts-for-python/highcharts-for-python-demos.git
+    ```
+
+2. Next, navigate to its directory:
+
+    ```
+    $ cd highcharts-for-python-demos
+
+    highcharts-for-python-demos/ (master)
+    $
+    ````
+
+3. Create a virtual environment:
+
+    ```
+    highcharts-for-python-demos/ (master)
+    $ python -m venv .venv
+    ```
+
+4. Then activate your virtual environment:
+
+    ```
+    highcharts-for-python-demos/ (master)
+    $ source .venv/Scripts/activate
+
+    (.venv)
+    highcharts-for-python-demos/ (master)
+    $
+    ```
+
+5. And install the requirements:
+
+    ```
+    (.venv)
+    highcharts-for-python-demos/ (master)
+    $ pip install -r requirements.txt
+    ```
+
+6. And finally, open up Jupyter Lab:
+
+    ```
+    (.venv)
+    highcharts-for-python-demos/ (master)
+    $ jupyter-lab
+    ```
+
+You should now see the set of notebooks included in the repo, along with relevant data files and other details.
+
+For example, to see how **Highcharts Core for Python** generates a basic line chart, you can open the Notebook at ``highcharts-core/line-charts/basic-line.ipynb``.
+
+Then just run the Notebook, and you should see the results.
+
+## Contributing to the Demos
+
+If you wish to contribute demos to this library:
+
+1. First, clone this Github repo:
+
+    ```
+    $ git clone [email protected]:highcharts-for-python/highcharts-for-python-demos.git
+    ```
+
+2. Next, navigate to its directory:
+
+    ```
+    $ cd highcharts-for-python-demos
+
+    highcharts-for-python-demos/ (master)
+    $
+    ````
+
+3. Create a virtual environment:
 
-Next, navigate to its directory:
+    ```
+    highcharts-for-python-demos/ (master)
+    $ python -m venv .venv
+    ```
 
-```
-$ cd highcharts-for-python-demos
+4. Activate your virtual environment:
 
-highcharts-for-python-demos/ (master)
-$
-````
+    ```
+    highcharts-for-python-demos/ (master)
+    $ source .venv/Scripts/activate
 
-Create a virtual environment:
+    (.venv)
+    highcharts-for-python-demos/ (master)
+    $
+    ```
 
-```
-highcharts-for-python-demos/ (master)
-$ python -m venv .venv
-```
+5. Install the requirements:
 
-Then activate your virtual environment:
+    ```
+    (.venv)
+    highcharts-for-python-demos/ (master)
+    $ pip install -r requirements.txt
+    ```
 
-```
-highcharts-for-python-demos/ (master)
-$ source .venv/Scripts/activate
+6. Install the pre-commit hook (which strips output from the Jupyter Notebooks on commit):
 
-(.venv)
-highcharts-for-python-demos/ (master)
-$
-```
+    ```
+    (.venv)
+    highcharts-for-python-demos/ (master)
+    $ pre-commit install
+    ```
 
-and install the requirements:
+7. Create a new branch in your repo that you will use for your changes.
 
-```
-(.venv)
-highcharts-for-python-demos/ (master)
-$ pip install -r requirements.txt
-```
+8. Either edit the existing Jupyter Notebooks or add new ones using the basic conventions and pattern that you'll find in our other demos.
 
-And finally, open up Jupyter Lab:
+9. Commit your changes and push them to this Github repo.
 
-```
-(.venv)
-highcharts-for-python-demos/ (master)
-$ jupyter-lab
-```
+10. File a Pull Request to merge changes from your branch to the ``develop`` branch.
 
-You should now see the set of notebooks included in the repo, along with relevant data files and other details. Browse through the repo, and look at the demos that you want to see. It should be fairly self-explanatory!
+And that's it! Thank you for your contributions, they are much appreciated.