Revised documentation.

Author: hcpchris

README.rst

@@ -382,8 +382,8 @@ And thanks to all those who've already contributed!
 Testing
 *********************
 
-We use `TravisCI <https://travisci.org>`_ for our build automation and
-`ReadTheDocs <https://readthedocs.org>`_ for our documentation.
+We use `TravisCI <https://travisci.com>`_ for our build automation and
+`ReadTheDocs <https://readthedocs.com>`_ for our documentation.
 
 Detailed information about our test suite and how to run tests locally can be
 found in our Testing Reference.

docs/_versus_alternatives.rst

@@ -98,7 +98,7 @@ some commonly-used alternatives:
  .. tab:: panel-highcharts
 
  The `panel-highcharts <https://pypi.org/project/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 

docs/api.rst

@@ -27,7 +27,7 @@ class in **Highcharts Core for Python**. These classes generally inherit from th
 :class:`HighchartsMeta <highcharts_core.metaclasses.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.
 

docs/api/_handling_defaults.rst

@@ -1,7 +1,7 @@
  *Explicit is better than implicit.*
  -- The Zen of Python
 
-`Highcharts JS <https://www.highcharts.com/>`_ has a *lot* of default values. These
+`Highcharts <https://www.highcharts.com/>`_ 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 <https://www.highcharts.com>`__ handles defaults is an elegant
+The way that `Highcharts (JS) <https://www.highcharts.com>`__ 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 <https://www.highcharts.com>`__ library, *nobody* wants to transmit or
+`Highcharts (JS) <https://www.highcharts.com>`__ 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 <python: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 <python:dict>`, nor to JSON. This has the advantage of maintaining consistent
-behavior with `Highcharts JS <https://www.highcharts.com/products/highcharts/>`__ while
+behavior with the `Highcharts (JS) <https://www.highcharts.com/>`__ 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.

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 <https://www.highcharts.com/>`_ options object (see the relevant
-`reference documentation <https://api.highcharts.com/highcharts/>`_).
+The structure of the **Highcharts Core for Python** library closely matches the structure
+of the `Highcharts Core <https://api.highcharts.com/highcharts/>`_ options object (see the 
+relevant `reference documentation <https://api.highcharts.com/highcharts/>`_).
 
 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 <highcharts_core.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 <highcharts_core.options>` module, with
  specific (complicated or extensive) sub-folders providing property-specific classes
  (e.g. the :mod:`.options.plot_options <highcharts_core.options.plot_options>`
  module defines all of the different configuration options for different series types,
  while the :mod:`.options.series <highcharts_core.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()

docs/contributing.rst

@@ -213,16 +213,16 @@ Docstrings
 Design Patterns and Standards
 ***************************************************
 
-`Highcharts JS <https://www.highcharts.com>`__ is a large, robust, and complicated JavaScript library. If in doubt, take
-a look at their extensive `documentation <https://www.highcharts.com/docs/index>`_ and in
-particular their `API reference <https://api.highcharts.com/highcharts>`_. Because
-**Highcharts for Python** wraps the Highcharts JS API, its design is heavily shaped by
+`Highcharts <https://www.highcharts.com>`__ is a large, robust, and complicated suite of 
+JavaScript libraries. If in doubt, take a look at the extensive 
+`documentation <https://www.highcharts.com/docs/index>`_ and in particular the 
+`API reference <https://api.highcharts.com/highcharts>`_. 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
 =======================================================

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 <faq_licensing>` above).
 
-You are welcome to review the source code for any library in the toolkit on `Github <https://github.com/highcharts-for-python>`__, including for `Highcharts Core for Python <https://github.com/highcharts-for-python/highcharts-core>`__.
+You are welcome to review the source code for any library in the toolkit on 
+`Github <https://github.com/highcharts-for-python>`__, including for 
+`Highcharts Core for Python <https://github.com/highcharts-for-python/highcharts-core>`__.
 
-**Can I fork the toolkit?**
+**Can I fork the toolkit or a library in the toolkit?**
 
 .. warning::
 

docs/using.rst

@@ -150,9 +150,8 @@ literally - any frontend framework. Whether your Python application is relying o
 `Flask <https://flask.palletsprojects.com/en/2.2.x/>`_,
 `Django <https://www.djangoproject.com/>`_, `FastAPI <https://fastapi.tiangolo.com/>`_,
 `Pyramid <https://trypyramid.com/>`_, `Tornado <https://www.tornadoweb.org/en/stable/>`_,
-or some completely home-grown solution all Highcharts for
-Python needs is a place where `Highcharts <https://www.highcharts.com>`__ JavaScript
-code can be executed.
+or some completely home-grown solution all, Highcharts for Python needs is a place where 
+`Highcharts <https://www.highcharts.com>`__ 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 

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,27 +14,28 @@ 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
  convention.
 #. 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 <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 <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::

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 </api>`.
+ you to navigate the extensive :doc:`Highcharts Core for Python API </api>`.
 
  .. code-block:: python