Skip to content

Commit dfd7977

Browse files
craigbarrattcraigbarratt
committed
changed docs theme to sphinx_rtd_theme; split out overview
1 parent 8834dc1 commit dfd7977

File tree

3 files changed

+77
-70
lines changed

3 files changed

+77
-70
lines changed

‎docs/conf.py‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,7 @@
1414
# import sys
1515
# sys.path.insert(0, os.path.abspath('.'))
1616

17+
import sphinx_rtd_theme
1718

1819
# -- Project information -----------------------------------------------------
1920

@@ -32,6 +33,7 @@
3233
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
3334
# ones.
3435
extensions = [
36+
'sphinx_rtd_theme',
3537
]
3638

3739
# Add any paths that contain templates here, relative to this directory.
@@ -48,7 +50,7 @@
4850
# The theme to use for HTML and HTML Help pages. See the documentation for
4951
# a list of builtin themes.
5052
#
51-
html_theme = 'alabaster'
53+
html_theme = "sphinx_rtd_theme"
5254

5355
# Add any paths that contain custom static files (such as style sheets) here,
5456
# relative to this directory. They are copied after the builtin static files,

‎docs/index.rst‎

Lines changed: 5 additions & 69 deletions
Original file line numberDiff line numberDiff line change
@@ -3,82 +3,18 @@ Pyscript: Python Scripting for Home Assistant
33

44
|GitHub Release| |License| |hacs| |Project Maintenance|
55

6-
Overview
7-
--------
8-
9-
This HACS custom integration allows you to write Python functions and
10-
scripts that can implement a wide range of automation, logic and
11-
triggers. State variables are bound to Python variables and services are
12-
callable as Python functions, so it’s easy and concise to implement
13-
logic.
14-
15-
Functions you write can be configured to be called as a service or run
16-
upon time, state-change or event triggers. Functions can also call any
17-
service, fire events and set state variables. Functions can sleep or
18-
wait for additional changes in state variables or events, without
19-
slowing or affecting other operations. You can think of these functions
20-
as small programs that run in parallel, independently of each other, and
21-
they could be active for extended periods of time.
22-
23-
State, event and time triggers are specified by Python function
24-
decorators (the “@” lines immediately before each function definition).
25-
A state trigger can be any Python expression using state variables - the
26-
trigger is evaluated only when a state variable it references changes,
27-
and the trigger occurs when the expression is true or non-zero. A time
28-
trigger could be a single event (eg: date and time), a repetitive event
29-
(eg: at a particular time each day or weekday, daily relative to sunrise
30-
or sunset or any regular time period within an optional range) or using
31-
cron syntax (where events occur periodically based on a concise
32-
specification of ranges of minutes, hours, days of week, days of month
33-
and months). An event trigger specifies the event type, and an optional
34-
Python trigger test based on the event data that runs the Python
35-
function if true.
36-
37-
Pyscript implements a Python interpreter using the ast parser output, in
38-
a fully async manner. That allows several of the “magic” features to be
39-
implemented in a seamless Pythonic manner, such as binding of variables
40-
to states and functions to services. Pyscript supports imports, although
41-
by default the valid import list is restricted for security reasons
42-
(there is a configuration option ``allow_all_imports`` to allow all
43-
imports). Pyscript supports all language features except generators and
44-
``yield``. Pyscript provides a handful of additional built-in functions
45-
that connect to HASS features, like logging, accessing state variables
46-
as strings (if you need to compute their names dynamically), sleeping
47-
and waiting for triggers.
48-
49-
Pyscript also provides a kernel that interfaces with the Jupyter
50-
front-ends (eg, notebook, console and lab). That allows you to develop
51-
and test pyscript code interactively. Plus you can interact with much of
52-
HASS by looking at state variables, calling services etc, in a similar
53-
way to `HASS
54-
CLI <https://github.com/home-assistant-ecosystem/home-assistant-cli>`__,
55-
although the CLI provides status on many other parts of HASS.
56-
57-
For more information about the Jupyter kernel, see the
58-
`README <https://github.com/craigbarratt/hass-pyscript-jupyter/blob/master/README.md>`__.
59-
There is also a `Jupyter notebook
60-
tutorial <https://nbviewer.jupyter.org/github/craigbarratt/hass-pyscript-jupyter/blob/master/pyscript_tutorial.ipynb>`__,
61-
which can be downloaded and run interactively in Jupyter notebook
62-
connected to your live HASS with pyscript.
63-
64-
Pyscript provides functionality that complements the existing
65-
automations, templates and triggers. Pyscript is most similar to
66-
`AppDaemon <https://appdaemon.readthedocs.io/en/latest/>`__, and some
67-
similarities and differences are discussed in this `Wiki
68-
page <https://github.com/custom-components/pyscript/wiki/Comparing-Pyscript-to-AppDaemon>`__.
69-
Pyscript with Jupyter makes it extremely easy to learn, use and debug.
70-
Pyscripts presents a simplified and more integrated binding for Python
71-
scripting than `Python
72-
Scripts <https://www.home-assistant.io/integrations/python_script>`__,
73-
which requires a lot more expertise and scaffolding using direct access
74-
to Home Assistant internals.
6+
This HACS custom integration for Home Assistant allows you to write Python functions
7+
and scripts that can implement a wide range of automation, logic and triggers.
8+
State variables are bound to Python variables and services are callable as Python
9+
functions, so it’s easy and concise to implement logic.
7510

7611
Contents
7712
~~~~~~~~
7813

7914
.. toctree::
8015
:maxdepth: 3
8116

17+
overview
8218
installation
8319
configuration
8420
tutorial

‎docs/overview.rst‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
Overview
2+
--------
3+
4+
This HACS custom integration allows you to write Python functions and
5+
scripts that can implement a wide range of automation, logic and
6+
triggers. State variables are bound to Python variables and services are
7+
callable as Python functions, so it’s easy and concise to implement
8+
logic.
9+
10+
Functions you write can be configured to be called as a service or run
11+
upon time, state-change or event triggers. Functions can also call any
12+
service, fire events and set state variables. Functions can sleep or
13+
wait for additional changes in state variables or events, without
14+
slowing or affecting other operations. You can think of these functions
15+
as small programs that run in parallel, independently of each other, and
16+
they could be active for extended periods of time.
17+
18+
State, event and time triggers are specified by Python function
19+
decorators (the “@” lines immediately before each function definition).
20+
A state trigger can be any Python expression using state variables - the
21+
trigger is evaluated only when a state variable it references changes,
22+
and the trigger occurs when the expression is true or non-zero. A time
23+
trigger could be a single event (eg: date and time), a repetitive event
24+
(eg: at a particular time each day or weekday, daily relative to sunrise
25+
or sunset or any regular time period within an optional range) or using
26+
cron syntax (where events occur periodically based on a concise
27+
specification of ranges of minutes, hours, days of week, days of month
28+
and months). An event trigger specifies the event type, and an optional
29+
Python trigger test based on the event data that runs the Python
30+
function if true.
31+
32+
Pyscript implements a Python interpreter using the ast parser output, in
33+
a fully async manner. That allows several of the “magic” features to be
34+
implemented in a seamless Pythonic manner, such as binding of variables
35+
to states and functions to services. Pyscript supports imports, although
36+
by default the valid import list is restricted for security reasons
37+
(there is a configuration option ``allow_all_imports`` to allow all
38+
imports). Pyscript supports all language features except generators and
39+
``yield``. Pyscript provides a handful of additional built-in functions
40+
that connect to HASS features, like logging, accessing state variables
41+
as strings (if you need to compute their names dynamically), sleeping
42+
and waiting for triggers.
43+
44+
Pyscript also provides a kernel that interfaces with the Jupyter
45+
front-ends (eg, notebook, console and lab). That allows you to develop
46+
and test pyscript code interactively. Plus you can interact with much of
47+
HASS by looking at state variables, calling services etc, in a similar
48+
way to `HASS
49+
CLI <https://github.com/home-assistant-ecosystem/home-assistant-cli>`__,
50+
although the CLI provides status on many other parts of HASS.
51+
52+
For more information about the Jupyter kernel, see the
53+
`README <https://github.com/craigbarratt/hass-pyscript-jupyter/blob/master/README.md>`__.
54+
There is also a `Jupyter notebook
55+
tutorial <https://nbviewer.jupyter.org/github/craigbarratt/hass-pyscript-jupyter/blob/master/pyscript_tutorial.ipynb>`__,
56+
which can be downloaded and run interactively in Jupyter notebook
57+
connected to your live HASS with pyscript.
58+
59+
Pyscript provides functionality that complements the existing
60+
automations, templates and triggers. Pyscript is most similar to
61+
`AppDaemon <https://appdaemon.readthedocs.io/en/latest/>`__, and some
62+
similarities and differences are discussed in this `Wiki
63+
page <https://github.com/custom-components/pyscript/wiki/Comparing-Pyscript-to-AppDaemon>`__.
64+
Pyscript with Jupyter makes it extremely easy to learn, use and debug.
65+
Pyscripts presents a simplified and more integrated binding for Python
66+
scripting than `Python
67+
Scripts <https://www.home-assistant.io/integrations/python_script>`__,
68+
which requires a lot more expertise and scaffolding using direct access
69+
to Home Assistant internals.

0 commit comments

Comments
 (0)