From d8a12f8e1647b8dd2a52f44dab6bc810101246c6 Mon Sep 17 00:00:00 2001 From: rmorshea Date: Thu, 19 Aug 2021 01:28:31 -0700 Subject: [PATCH] improve heading legibility --- docs/source/_static/css/larger-headings.css | 18 +++++++++++++ docs/source/life-cycle-hooks.rst | 29 +++++++++------------ src/idom/core/hooks.py | 12 ++++----- 3 files changed, 36 insertions(+), 23 deletions(-) create mode 100644 docs/source/_static/css/larger-headings.css diff --git a/docs/source/_static/css/larger-headings.css b/docs/source/_static/css/larger-headings.css new file mode 100644 index 000000000..1bd5f5db2 --- /dev/null +++ b/docs/source/_static/css/larger-headings.css @@ -0,0 +1,18 @@ +h1, +h2, +h3, +h4, +h5, +h6 { + margin-top: 2em !important; + margin-bottom: 0 !important; + font-weight: 900 !important; +} + +h2 { + font-size: 1.8em !important; +} + +h3 { + font-size: 1.4em !important; +} diff --git a/docs/source/life-cycle-hooks.rst b/docs/source/life-cycle-hooks.rst index 5a8be3169..9060203d5 100644 --- a/docs/source/life-cycle-hooks.rst +++ b/docs/source/life-cycle-hooks.rst @@ -17,10 +17,8 @@ cases the :ref:`Basic Hooks` should be enough, however the remaining Basic Hooks =========== -Common hooks that should fulfill a majority of use cases. - -use_state +Use State --------- .. code-block:: @@ -45,8 +43,8 @@ of ``new_state``. .. note:: The identity of ``set_state`` is guaranteed to be preserved across renders. This - means it can safely be omitted from dependency lists in :ref:`use_effect` or - :ref:`use_callback`. + means it can safely be omitted from dependency lists in :ref:`Use Effect` or + :ref:`Use Callback`. Functional Updates @@ -92,7 +90,7 @@ result in a re-render: set_state(state) -use_effect +Use Effect ---------- .. code-block:: @@ -186,18 +184,15 @@ There are **three important subtleties** to note about using asynchronous effect Supplementary Hooks =================== -Hooks that fulfill some less common, but still important use cases using variations of -the :ref:`Basic Hooks`. - -use_reducer +Use Reducer ----------- .. code-block:: state, dispatch_action = use_reducer(reducer, initial_state) -An alternative and derivative of :ref:`use_state` the ``use_reducer`` hook, instead of +An alternative and derivative of :ref:`Use State` the ``use_reducer`` hook, instead of directly assigning a new state, allows you to specify an action which will transition the previous state into the next state. This transition is defined by a reducer function of the form ``(current_state, action) -> new_state``. The ``use_reducer`` hook then @@ -218,17 +213,17 @@ We can rework the :ref:`Functional Updates` counter example to use ``use_reducer The identity of the ``dispatch_action`` function is guaranteed to be preserved across re-renders throughout the lifetime of the component. This means it can safely - be omitted from dependency lists in :ref:`use_effect` or :ref:`use_callback`. + be omitted from dependency lists in :ref:`Use Effect` or :ref:`Use Callback`. -use_callback +Use Callback ------------ .. code-block:: memoized_callback = use_callback(lambda: do_something(a, b), [a, b]) -A derivative of :ref:`use_memo`, the ``use_callback`` hook returns a +A derivative of :ref:`Use Memo`, the ``use_callback`` hook returns a `memoized `_ callback. This is useful when passing callbacks to child components which check reference equality to prevent unnecessary renders. The of ``memoized_callback`` will only change when the given dependencies do. @@ -243,7 +238,7 @@ components which check reference equality to prevent unnecessary renders. The of -use_memo +Use Memo -------- .. code-block:: @@ -277,7 +272,7 @@ after) and should not incur side effects. to help enforce this. -use_ref +Use Ref ------- .. code-block:: @@ -290,7 +285,7 @@ The identity of the ``Ref`` object will be preserved for the lifetime of the com A ``Ref`` is most useful if you need to incur side effects since updating its ``.current`` attribute doesn't trigger a re-render of the component. You'll often use this -hook alongside :ref:`use_effect` or in response to component event handlers. +hook alongside :ref:`Use Effect` or in response to component event handlers. :ref:`The Game Snake` provides a good use case for ``use_ref``. diff --git a/src/idom/core/hooks.py b/src/idom/core/hooks.py index 5d5ecb8a9..98e473d88 100644 --- a/src/idom/core/hooks.py +++ b/src/idom/core/hooks.py @@ -49,7 +49,7 @@ def use_state( ) -> Tuple[ _StateType, Callable[[Union[_StateType, Callable[[_StateType], _StateType]]], None] ]: - """See the full :ref:`use_state` docs for details + """See the full :ref:`Use State` docs for details Parameters: initial_value: @@ -117,7 +117,7 @@ def use_effect( function: Optional[_EffectApplyFunc] = None, args: Optional[Sequence[Any]] = None, ) -> Optional[Callable[[_EffectApplyFunc], None]]: - """See the full :ref:`use_effect` docs for details + """See the full :ref:`Use Effect` docs for details Parameters: function: @@ -178,7 +178,7 @@ def use_reducer( reducer: Callable[[_StateType, _ActionType], _StateType], initial_value: _StateType, ) -> Tuple[_StateType, Callable[[_ActionType], None]]: - """See the full :ref:`use_reducer` docs for details + """See the full :ref:`Use Reducer` docs for details Parameters: reducer: @@ -225,7 +225,7 @@ def use_callback( function: Optional[_CallbackFunc] = None, args: Optional[Sequence[Any]] = (), ) -> Union[_CallbackFunc, Callable[[_CallbackFunc], _CallbackFunc]]: - """See the full :ref:`use_callback` docs for details + """See the full :ref:`Use Callback` docs for details Parameters: function: the function whose identity will be preserved @@ -270,7 +270,7 @@ def use_memo( function: Optional[Callable[[], _StateType]] = None, args: Optional[Sequence[Any]] = None, ) -> Union[_StateType, Callable[[Callable[[], _StateType]], _StateType]]: - """See the full :ref:`use_memo` docs for details + """See the full :ref:`Use Memo` docs for details Parameters: function: The function to be memoized. @@ -335,7 +335,7 @@ def empty(self) -> bool: def use_ref(initial_value: _StateType) -> Ref[_StateType]: - """See the full :ref:`use_state` docs for details + """See the full :ref:`Use State` docs for details Parameters: initial_value: The value initially assigned to the reference.