added release_history with new changes; create new limitations section

Author: craigbarratt

docs/index.rst

@@ -20,6 +20,7 @@ Contents
    tutorial
    reference
    contributing
+   release_history
    useful_links
 
 .. |GitHub Release| image:: https://img.shields.io/github/release/custom-components/pyscript.svg?style=for-the-badge

docs/overview.rst

@@ -35,11 +35,13 @@ implemented in a seamless Pythonic manner, such as binding of variables
 to states and functions to services. Pyscript supports imports, although
 by default the valid import list is restricted for security reasons
 (there is a configuration option ``allow_all_imports`` to allow all
-imports). Pyscript supports all language features except generators and
-``yield``. Pyscript provides a handful of additional built-in functions
-that connect to HASS features, like logging, accessing state variables
-as strings (if you need to compute their names dynamically), sleeping
-and waiting for triggers.
+imports). Pyscript supports almost all Python language features except
+generators, ``yield`` and user-defined function decorators
+(see `language limitations <reference.html#language-limitations>`__).
+Pyscript provides a handful of additional built-in functions that connect
+to HASS features, like logging, accessing state variables as strings
+(if you need to compute their names dynamically), sleeping and waiting
+for triggers.
 
 Pyscript also provides a kernel that interfaces with the Jupyter
 front-ends (eg, notebook, console and lab). That allows you to develop

docs/reference.rst

@@ -137,6 +137,7 @@ to this that in a ``@state_trigger`` expression, undefined state variables will
 
 Two virtual attribute values are available when you use a variable directly as ``DOMAIN.entity.attr``
 or call ``state.get("DOMAIN.entity.attr")``:
+
 - ``last_changed`` is the last UTC time the state value was changed (not the attributes)
 - ``last_updated`` is the last UTC time the state entity was updated
 
@@ -661,7 +662,8 @@ level will not appear in the log. Each log message function uses a log name of t
    custom_components.pyscript.file.FILENAME.FUNCNAME
 
 where ``FUNCNAME`` is the name of the top-level Python function (e.g., the one called by a trigger
-or service), defined in the script file ``FILENAME.py``. See the XXXX
+or service), defined in the script file ``FILENAME.py``. See the `Global Context <#global-context>`__
+section to see the logging path for other cases.
 
 That allows you to set the log level for each Python top-level function separately if necessary.
 That setting also applies to any other Python functions that the top-level Python function calls.
@@ -1296,3 +1298,42 @@ With this in place, ``state.persist()`` will be called every time this script is
 ``pyscript.last_light_on`` state variable state will persist between HASS restarts. If ``state.persist``
 is not called on a particular state variable before HASS stops, then that state variable will not be
 preserved on the next start.
+
+Language Limitations
+^^^^^^^^^^^^^^^^^^^^
+
+Pyscript implements a Python interpreter in a fully-async manner, which means it can run safely in the
+main HASS event loop.
+
+The language coverage is relatively complete, but it's quite possible there are discrepancies with Python
+in certain cases.  If so, please report them.
+
+Here are some areas where pyscript differs from real Python:
+
+- The pyscript-specific function names and state names that contain a period are treated as plain
+  identifiers that contain a period, rather than an attribute (to the right of the period) of an object
+  (to the left of the period). For example, while ``pyscript.reload`` and ``state.get`` are functions, ``pyscript``
+  and ``state`` aren't defined. However, if you set ``pyscript`` or ``state`` to some value (ie: assign them
+  as a variable), then ``pyscript.reload`` and ``state.get`` are now treated as accessing those attributes
+  in the ``pyscript`` or ``state`` object, rather than calls to the builtin functions, which are no longer
+  available. That's similar to regular Python, where if you set ``bytes`` to some value, the ``bytes.fromhex``
+  function is no longer available.
+- Since pyscript is async, it detects whether functions are real or async, and calls them in the
+  correct manner. So it's not necessary to use ``async`` and ``await`` in pyscript code - they are optional.
+- All pyscript functions are async. So if you call a Python module that takes a pyscript function as
+  a callback argument, that argument is an async function, not a normal function.  So a Python module
+  won't be able to call that pyscript function unless it uses ``await``, which requires that function to
+  be declared ``async``. Unless the Python module is designed to support async callbacks, it is not
+  currently possible to have Python modules and packages call pyscript functions. The workaround is
+  to move your callbacks from pyscript and make them native Python functions; see `Importing <#importing>`__.
+
+A handful of language features are not supported:
+
+- generators and the ``yield`` statement; these are difficult to implement in an interpreter.
+- function decorators, beyond the builtin ones, are not yet supported.  If there is interest, support
+  for function decorators could be added.  Additionally, the builtin function decorators aren't
+  functions that can be called and used in-line. There is a feature request to add this.
+
+Pyscript can call Python modules and packages, so you can always write your own native Python code
+(eg, if you need a generator or other unsupported feature) that can be called by psycript
+(see `Importing <#importing>`__ for how to create and import native Python modules in pyscript).

docs/release_history.rst

@@ -0,0 +1,41 @@
+Release History
+===============
+
+The releases and releae notes are available on `GitHub <https://github.com/custom-components/pyscript/releases>`__.
+Use HACS to install different versions of pyscript.
+
+You can also install the master (head of tree) version from GitHub, either using HACS or manually.
+
+The latest release is 0.32, released on October 21, 2020.  Here is the `stable documentation <https://hacs-pyscript.readthedocs.io/en/stable>`__
+for that release.
+
+Since that release, the master (head of tree) version in GitHub has several new features and bug fixes.
+Here is the master `latest documentation <https://hacs-pyscript.readthedocs.io/en/latest>`__.
+
+The new features since 0.32 in master include:
+
+- Pyscript state variables (entity_ids) can be persisted across pyscript reloads and HASS restarts,
+  from @swazrgb and @dlashua (#48).
+- The ``hass`` object is available in all pyscript global contexts if the ``hass_is_global`` configuration parameter
+  is true (default false). This allows access to HASS internals that might not be otherwise exposed by pyscript.
+  Use with caution. PR #51.
+- Improvements to UI config flow, including allows parameters to be updated, and the UI reload now works the same
+  as the ``pyscript.reload`` service call, submitted by @raman325 (#53)
+- State variables now support virtual attributes last_changed and last_updated for the UTC time when state values
+  or any attribute was last changed.
+- ``@state_trigger`` and ``task.wait_until`` now have an optional ``state_hold`` duration in seconds that requires
+  the state trigger to remain true for that period of time. The trigger occurs after that time elapses. If the state
+  trigger changes to false before the time expires, the process of waiting for a new trigger starts over.
+- ``@time_active`` now has an optional ``hold_off`` duration in seconds, which ignores a new trigger if the last
+  one happened within that time.  Can be used for rate limiting or debouncing. Also, ``@time_active`` can now take
+  zero time range arguments, in case you want to just specify ``hold_off``.
+- Added inbound ``context`` variable to trigger functions and support optional ``context`` setting on state,
+  event firing and service calls. Proposal and PR by @dlashua (#50, #60).
+- Logbook now supported using ``context`` and informational message based on trigger type. Proposal and PR by
+  @dlashua (#50, #62).
+
+The bug fixes since 0.32 in master include:
+
+- Jupyter autocomplete now works on multiline code blocks.
+- Improved error message reporting for syntax errors inside f-strings.
+- Fixed incorrect global context update on calling module that, in turn, does a callback (#58)

docs/useful_links.rst

@@ -1,10 +1,10 @@
 Useful Links
 ============
 
--  `Documentation <https://hacs-pyscript.readthedocs.io/en/latest>`__
+-  `Documentation stable <https://hacs-pyscript.readthedocs.io/en/stable>`__: latest release
+-  `Documentation latest <https://hacs-pyscript.readthedocs.io/en/latest>`__: current master in GitHub
 -  `Issues <https://github.com/custom-components/pyscript/issues>`__
 -  `Wiki <https://github.com/custom-components/pyscript/wiki>`__
--  `GitHub repository <https://github.com/custom-components/pyscript>`__
-   (please add a star if you like pyscript!)
+-  `GitHub repository <https://github.com/custom-components/pyscript>`__ (please add a star if you like pyscript!)
 -  `Jupyter notebook
    tutorial <https://nbviewer.jupyter.org/github/craigbarratt/hass-pyscript-jupyter/blob/master/pyscript_tutorial.ipynb>`__