add docs + use flake8-idom-hooks on idom itself

Author: rmorshea

docs/source/conf.py

@@ -109,7 +109,11 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-# html_static_path = ["static"]
+html_static_path = ["static"]
+
+# These paths are either relative to html_static_path
+# or fully qualified paths (eg. https://...)
+html_css_files = ["css/interactive-widget.css"]
 
 # Custom sidebar templates, must be a dictionary that maps document names
 # to template names.

docs/source/exts/interactive_widget.py

@@ -17,44 +17,6 @@ def run(self):
             raw(
                 "",
                 f"""
-                <style>
-                .interactive {{
-                    -webkit-transition: 0.2s ease-out;
-                    -moz-transition: 0.2s ease-out;
-                    -o-transition: 0.2s ease-out;
-                    transition: 0.2s ease-out;
-                }}
-                .widget-container {{
-                    padding: 15px;
-                    background-color: #fcfcfc;
-                    min-height: 75px;
-                }}
-                .center-content {{
-                    display: flex;
-                    align-items: center;
-                    justify-content: center;
-                }}
-                .enable-widget-button {{
-                    padding: 10px;
-                    color: #ffffff !important;
-                    text-transform: uppercase;
-                    text-decoration: none;
-                    background: #3980b9;
-                    border: 2px solid #3980b9 !important;
-                    transition: all 0.2s ease 0s;
-                    box-shadow: 0 5px 10px grey;
-                }}
-                .enable-widget-button:hover {{
-                    color: #3980b9 !important;
-                    background: #ffffff;
-                    transition: all 0.2s ease 0s;
-                }}
-                .enable-widget-button:focus {{
-                    outline: 0 !important;
-                    transform: scale(0.98);
-                    transition: all 0.2s ease 0s;
-                }}
-                </style>
                 <div>
                     <div id="{container_id}" class="interactive widget-container center-content" style="" />
                     <script async type="module">

docs/source/life-cycle-hooks.rst

@@ -301,20 +301,63 @@ hook alongside :ref:`use_effect` or in response to element event handlers.
 **Rules of Hooks**
 ------------------
 
-Under construction... for now refer to
-`React's documentation <https://reactjs.org/docs/hooks-rules.html>`_ on this topic.
+Hooks are just normal Python functions, but there's a bit of magic to them, and in order
+for that magic to work you've got to follow two rules. Thankfully we supply a
+`Flake8 Linter Plugin`_ to help enforce them.
 
-.. note::
 
-    We're `working on a linter <https://github.com/idom-team/idom/issues/202>`_ to help
-    enforce the rules.
+Only call hooks at the top level
+--------------------------------
+
+**Don't call hooks inside loops, conditions, or nested functions.** Instead you must
+always call hooks at the top level of your functions. By adhering to this rule you
+ensure that hooks are always called in the exact same order. This fact is what allows
+IDOM to preserve the state of hooks between multiple calls to ``useState`` and
+``useEffect`` calls.
+
+
+Only call hooks from IDOM functions
+-----------------------------------
+
+**Don't call hooks from regular Python functions.** Instead you should:
+
+- ✅ Call Hooks from an element's render function.
+
+- ✅ Call Hooks from another custom hook
+
+Following this rule ensures stateful logic for IDOM element is always clearly
+separated from the rest of your codebase.
+
+
+Flake8 Plugin
+-------------
+
+We provide a Flake8 plugin called `flake8-idom-hooks <Flake8 Linter Plugin>`_ that helps
+to enforce the two rules described above. You can ``pip`` install it directly, or with
+the ``lint`` extra for IDOM:
+
+.. code-block:: bash
+
+    pip install idom[stable,lint]
+
+Once installed running ``flake8`` on your could will start catching errors:
+
+.. code-block:: bash
+
+    flake8 my_idom_elements.py
+
+.. code-block:: text
+
+    ./my_idom_elements:10:8 ROH102 hook 'use_effect' used inside if statement
+    ./my_idom_elements:23:4 ROH102 hook 'use_state' used outside element or hook definition
 
+See the Flake8 docs for
+`more info <https://flake8.pycqa.org/en/latest/user/configuration.html>`__.
 
 .. links
 .. =====
 
 .. _React Hooks: https://reactjs.org/docs/hooks-reference.html
 .. _side effects: https://en.wikipedia.org/wiki/Side_effect_(computer_science)
 .. _memoization: https://en.wikipedia.org/wiki/Memoization
-.. _premature optimization: https://en.wikiquote.org/wiki/Donald_Knuth#Computer_Programming_as_an_Art_(1974)
-.. _gh issues: https://github.com/idom-team/idom/issues
+.. _Flake8 Linter Plugin: https://github.com/idom-team/flake8-idom-hooks

docs/source/static/css/interactive-widget.css

@@ -0,0 +1,36 @@
+.interactive {
+  -webkit-transition: 0.2s ease-out;
+  -moz-transition: 0.2s ease-out;
+  -o-transition: 0.2s ease-out;
+  transition: 0.2s ease-out;
+}
+.widget-container {
+  padding: 15px;
+  background-color: #fcfcfc;
+  min-height: 75px;
+}
+.center-content {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+.enable-widget-button {
+  padding: 10px;
+  color: #ffffff !important;
+  text-transform: uppercase;
+  text-decoration: none;
+  background: #3980b9;
+  border: 2px solid #3980b9 !important;
+  transition: all 0.2s ease 0s;
+  box-shadow: 0 5px 10px grey;
+}
+.enable-widget-button:hover {
+  color: #3980b9 !important;
+  background: #ffffff;
+  transition: all 0.2s ease 0s;
+}
+.enable-widget-button:focus {
+  outline: 0 !important;
+  transform: scale(0.98);
+  transition: all 0.2s ease 0s;
+}

requirements/extras.txt

@@ -9,3 +9,6 @@ matplotlib
 htm
 pyalect
 tagged
+
+# extra=lint
+flake8-idom-hooks

requirements/lint.txt

@@ -1,3 +1,4 @@
 black
 flake8
 pep8-naming
+flake8-idom-hooks

setup.cfg

@@ -8,7 +8,7 @@ warn_unused_ignores = True
 ignore = E203, E266, E501, W503, F811, N802
 max-line-length = 88
 max-complexity = 18
-select = B,C,E,F,W,T4,B9,N
+select = B,C,E,F,W,T4,B9,N,ROH
 exclude =
     idom/client/app/node_modules/*
     docs/source/examples/*