diff --git a/README.rst b/README.rst index 7ff1e7bc..2e2b725b 100644 --- a/README.rst +++ b/README.rst @@ -382,8 +382,8 @@ And thanks to all those who've already contributed! Testing ********************* -We use `TravisCI `_ for our build automation and -`ReadTheDocs `_ for our documentation. +We use `TravisCI `_ for our build automation and +`ReadTheDocs `_ for our documentation. Detailed information about our test suite and how to run tests locally can be found in our Testing Reference. diff --git a/docs/_versus_alternatives.rst b/docs/_versus_alternatives.rst index bc542cf2..f1e3e46f 100644 --- a/docs/_versus_alternatives.rst +++ b/docs/_versus_alternatives.rst @@ -98,7 +98,7 @@ some commonly-used alternatives: .. tab:: panel-highcharts The `panel-highcharts `_ library is - - honestly - fantastic. It is a excellent wrapper for the Highcharts Core (JS) library to + honestly - fantastic. It is a excellent wrapper for the Highcharts (JS) suite to enable exploratory data analysis (EDA) in Jupyter Notebooks or in Holoviz web applications. @@ -110,14 +110,17 @@ some commonly-used alternatives: to the Highcharts API. In practice, this forces the developer to switch between Pythonic ``snake_case`` convention and JavaScript ``camelCase`` conventions within the same code. Not a big problem, but annoying. + * To really benefit from its capabilities, it requires a fair bit of Holoviz + boilerplate and widget configuration, which can be complicated, verbose, and + "fiddly". .. tip:: **When to use it?** - If your use case was satisfied with Highcharts Core visualizations only, and involved - highly-interactive exploratory data analysis in a Jupyter Labs/Notebook environment, - it may be worth considering this library. + If your use case is limited to highly-interactive exploratory data analysis in a + Jupyter Labs/Notebook environment and you are willing to construct some complicated + Holoviz widget configuration code, it may be worth considering this library. However, those are some pretty specific gating conditions. For integration with a non-Jupyter application? That's not what the **Highcharts for Python Toolkit** was diff --git a/docs/api.rst b/docs/api.rst index 8d74f8f6..65a72515 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -27,7 +27,7 @@ class in **Highcharts Core for Python**. These classes generally inherit from th :class:`HighchartsMeta ` metaclass, which provides each class with a number of standard methods. -These methods are the "workhorses" of the **Highcharts for Python Tolkit** and you will be relying +These methods are the "workhorses" of the **Highcharts for Python Toolkit** and you will be relying heavily on them when using the library. Thankfully, their signatures and behavior is generally consistent - even if what happens "under the hood" is class-specific at times. diff --git a/docs/api/_handling_defaults.rst b/docs/api/_handling_defaults.rst index ce153413..b97cfcc2 100644 --- a/docs/api/_handling_defaults.rst +++ b/docs/api/_handling_defaults.rst @@ -1,7 +1,7 @@ *Explicit is better than implicit.* -- The Zen of Python -`Highcharts JS `_ has a *lot* of default values. These +`Highcharts `_ has a *lot* of default values. These default values are generally applied if a JavaScript property is ``undefined`` (missing or otherwise not specified), which is different from the JavaScript value of ``null``. @@ -15,23 +15,23 @@ While my Pythonic instinct is to: doing so would introduce a massive problem: It would bloat data transferred on the wire *unnecessarily*. -The way that `Highcharts JS `__ handles defaults is an elegant +The way that `Highcharts (JS) `__ handles defaults is an elegant compromise between explicitness and the practical reality of making your code readable. Why make a property explicit in a configuration string if you don't care about it? Purity is only valuable to a point. And with thousands of properties across the -`Highcharts JS `__ library, *nobody* wants to transmit or +`Highcharts (JS) `__ suite, *nobody* wants to transmit or maintain thousands of property configurations if it can be avoided. -For that reason, the **Highcharts for Python** toolkit explicitly breaks Pythonic +For that reason, the **Highcharts for Python Toolkit** explicitly breaks Pythonic convention: when an object's property returns :obj:`None `, that has the -equivalent meaning of "Highcharts JS/Stock will apply the Highcharts default for this +equivalent meaning of "Highcharts (JS) will apply the Highcharts default for this property". These properties will *not* be serialized, either to a JS literal, nor to a :class:`dict `, nor to JSON. This has the advantage of maintaining consistent -behavior with `Highcharts JS `__ while +behavior with the `Highcharts (JS) `__ suite while still providing an internally consistent logic to follow. .. note:: - There's an item on the **Highcharts for Python** :doc:`roadmap <../toolkit>` (:issue:`1`) + There's an item on the **Highcharts for Python** :doc:`roadmap <../toolkit>` (:issue:`12`) to *optionally* surface defaults when explicitly requested. Not sure when it will be implemented, but we'll get there at some point. diff --git a/docs/api/_module_structure.rst b/docs/api/_module_structure.rst index 176a03a4..ece5953d 100644 --- a/docs/api/_module_structure.rst +++ b/docs/api/_module_structure.rst @@ -1,7 +1,7 @@ -The structure of the **Highcharts for Python** library closely matches the structure -of the `Highcharts JS `_ options object (see the relevant -`reference documentation `_). +The structure of the **Highcharts Core for Python** library closely matches the structure +of the `Highcharts Core `_ options object (see the +relevant `reference documentation `_). At the root of the library - importable from ``highcharts_core`` you will find the :mod:`highcharts_core.highcharts` module. This module is a catch-all importable module, @@ -10,11 +10,13 @@ modules. .. note:: - Whlie you can access all of the **Highcharts for Python** classes from + Whlie you can access all of the **Highcharts Core for Python** classes from ``highcharts_core.highcharts``, if you want to more precisely navigate to specific class definitions you can do fairly easily using the folder organization and naming conventions used in the library. + *This is the recommended best practice to maximize performance*. + In the root of the ``highcharts_core`` library you can find universally-shared class definitions, like :mod:`.metaclasses ` which contains the :class:`HighchartsMeta` definition and the :class:`JavaScriptDict` @@ -25,33 +27,10 @@ modules. definitions for classes that are referenced or used throughout the other class definitions. - And you can find the Highcharts JS ``options`` object and all of its + And you can find the Highcharts Core ``options`` object and all of its properties defined in the :mod:`.options ` module, with specific (complicated or extensive) sub-folders providing property-specific classes (e.g. the :mod:`.options.plot_options ` module defines all of the different configuration options for different series types, while the :mod:`.options.series ` module defines all of the classes that represent :term:`series` of data in a given chart). - -.. tip:: - - To keep things simple, we recommend importing classes you need directly from the - :mod:`highcharts_core.highcharts` module. There are two paths to do so easily: - - .. code-block:: python - - # APPROACH #1: Import the highcharts module, and access its child classes directly. - # for example by now calling highcharts.Chart(). - from highcharts_core import highcharts - - my_chart = highcharts.Chart() - my_shared_options = highcharts.SharedOptions() - - my_line_series = highcharts.options.series.area.LineSeries() - - # APPROACH #2: Import a specific class or module by name from the "highcharts" module. - from highcharts_core.highcharts import Chart, SharedOptions, options - - my_chart = Chart() - my_shared_options = SharedOptions() - my_line_series = options.series.area.LineSeries() diff --git a/docs/contributing.rst b/docs/contributing.rst index 63945d05..1ffd6e0e 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -213,16 +213,16 @@ Docstrings Design Patterns and Standards *************************************************** -`Highcharts JS `__ is a large, robust, and complicated JavaScript library. If in doubt, take -a look at their extensive `documentation `_ and in -particular their `API reference `_. Because -**Highcharts for Python** wraps the Highcharts JS API, its design is heavily shaped by +`Highcharts `__ is a large, robust, and complicated suite of +JavaScript libraries. If in doubt, take a look at the extensive +`documentation `_ and in particular the +`API reference `_. Because +**Highcharts for Python** wraps the Highcharts JS API, its design is heavily shaped by Highcharts JS' own design - as one should expect. However, one of the main goals of **Highcharts for Python** is to make the Highcharts JS -library a little more Pythonic in terms of its design to make it easier for Python -developers to leverage it. Here are the notable design patterns that have been adopted -that you should be aware of: +library a little more Pythonic to make it easier for Python developers to leverage it. +Here are the notable design patterns that have been adopted that you should be aware of: Code Style: Python vs JavaScript Naming Conventions ======================================================= diff --git a/docs/faq.rst b/docs/faq.rst index 300ff46c..10a712a1 100644 --- a/docs/faq.rst +++ b/docs/faq.rst @@ -20,6 +20,8 @@ This documentation is a great place to start, but we're here to help! ----------------- +.. _faq_licensing: + *********************** Licensing *********************** @@ -60,9 +62,11 @@ Open Source Yes. The **Highcharts for Python Toolkit** toolkit is open source (but not free - see :ref:`licensing ` above). -You are welcome to review the source code for any library in the toolkit on `Github `__, including for `Highcharts Core for Python `__. +You are welcome to review the source code for any library in the toolkit on +`Github `__, including for +`Highcharts Core for Python `__. -**Can I fork the toolkit?** +**Can I fork the toolkit or a library in the toolkit?** .. warning:: diff --git a/docs/using.rst b/docs/using.rst index 50937ad9..fc12224f 100644 --- a/docs/using.rst +++ b/docs/using.rst @@ -150,9 +150,8 @@ literally - any frontend framework. Whether your Python application is relying o `Flask `_, `Django `_, `FastAPI `_, `Pyramid `_, `Tornado `_, -or some completely home-grown solution all Highcharts for -Python needs is a place where `Highcharts `__ JavaScript -code can be executed. +or some completely home-grown solution all, Highcharts for Python needs is a place where +`Highcharts `__ JavaScript code can be executed. All of those frameworks mentioned have their own best practices for organizing their application structures, and those best practices should *always* take priority. Even in a diff --git a/docs/using/_code_style_naming_conventions.rst b/docs/using/_code_style_naming_conventions.rst index 47b576f0..5a5767d1 100644 --- a/docs/using/_code_style_naming_conventions.rst +++ b/docs/using/_code_style_naming_conventions.rst @@ -1,7 +1,7 @@ *There are only two hard things in Computer Science: cache invalidation and naming things.* -- Phil Karlton -Highcharts Stock is a JavaScript library, and as such it adheres to the code conventions +Highcharts Core is a JavaScript library, and as such it adheres to the code conventions that are popular (practically standard) when working in JavaScript. Chief among these conventions is that variables and object properties (keys) are typically written in ``camelCase``. @@ -14,11 +14,11 @@ convention, Python generally skews towards the ``snake_case`` convention. For most Python developers, using ``snake_case`` is the "default" mindset. Most of your Python code will use ``snake_case``. So having to switch into ``camelcase`` to interact -with Highcharts Stock forces us to context switch, increases cognitive load, and is an +with Highcharts Core forces us to context switch, increases cognitive load, and is an easy place for us to overlook things and make a mistake that can be quite annoying to track down and fix later. -Therefore, when designing the **Highcharts for Python** toolkit, we made several carefully +Therefore, when designing the **Highcharts for Python Toolkit**, we made several carefully considered design choices when it comes to naming conventions: #. All **Highcharts for Python** classes follow the Pythonic ``PascalCase`` class-naming @@ -26,15 +26,16 @@ considered design choices when it comes to naming conventions: #. All **Highcharts for Python** properties and methods follow the Pythonic ``snake_case`` property/method/variable/function-naming convention. #. All *inputs* to properties and methods support *both* ``snake_case`` and - ``camelCase`` (aka ``mixedCase``) convention by default. This means that you can take - something directly from Highcharts JavaScript code and supply it to the - **Highcharts for Python** toolkit without having to convert case or conventions. But if - you are constructing and configuring something directly in Python using explicit - :ref:`deserialization methods `, you can use ``snake_case`` - if you prefer (and most Python developers will prefer). + ``camelCase`` (aka ``mixedCase``) convention by default. + + This means that you can take something directly from Highcharts JavaScript code and + supply it to the **Highcharts for Python Toolkit** without having to convert case or + conventions. But if you are constructing and configuring something directly in Python + using explicit :ref:`deserialization methods `, you can use + ``snake_case`` if you prefer (and most Python developers will prefer). For example, if you supply a JSON file to a ``from_json()`` method, that file can - leverage Highcharts JS natural ``camelCase`` convention OR Highcharts for Python's + leverage Highcharts (JS) natural ``camelCase`` convention OR Highcharts for Python's ``snake_case`` convention. .. warning:: @@ -45,7 +46,7 @@ considered design choices when it comes to naming conventions: methods expect ``snake_case`` properties to be supplied as keywords. #. All *outputs* from serialization methods (e.g. ``to_dict()`` or ``to_js_literal()``) - will produce outputs that are Highcharts JS-compatible, meaning that they apply the + will produce outputs that are Highcharts (JS)-compatible, meaning that they apply the ``camelCase`` convention. .. tip:: diff --git a/docs/using/_importing.rst b/docs/using/_importing.rst index f3187ead..a33735a4 100644 --- a/docs/using/_importing.rst +++ b/docs/using/_importing.rst @@ -8,7 +8,7 @@ This method of importing **Highcharts for Python** objects yields the fastest performance for the ``import`` statement. However, it is more verbose and requires - you to navigate the extensive :doc:`Highcharts for Python API `. + you to navigate the extensive :doc:`Highcharts Core for Python API `. .. code-block:: python diff --git a/docs/visualizations.rst b/docs/visualizations.rst index 62f3a673..4a8c8b16 100644 --- a/docs/visualizations.rst +++ b/docs/visualizations.rst @@ -8,7 +8,7 @@ Supported Visualizations -------------- -As the tables below make clear, the **Highcharts for Python Toolkit** toolkit and the +As the tables below make clear, the **Highcharts for Python Toolkit** and the `Highcharts `__ suite of JavaScript libraries are likely the single most comprehensive suite of data visualization tools available in the market. With over 70 (seventy!) distinct data visualizations and 50 (fifty!)