Commit cb3786d7 authored by Yakubov, Sergey's avatar Yakubov, Sergey
Browse files

Merge branch '22-update-documentation' into 'main' 

Update documentation

Closes #22

See merge request ndip/public-packages/nova-mvvm!21
parents 7ecf3ddb a016f6e3

.readthedocs.yml

+2 −4
Original line number Diff line number Diff line
@@ -6,9 +6,7 @@ build: 
    python: "3.12"

  jobs:

    post_create_environment:

      - pip install altair sphinx-rtd-theme==3.0.0rc3 tomli sphinxcontrib-napoleon

      - pip install .

    pre_build:

     - SPHINX_APIDOC_OPTIONS=members,show-inheritance sphinx-apidoc -o docs/source src

      - pip install altair sphinx-rtd-theme tomli sphinxcontrib-napoleon poetry

      - pip install .[pyqt5,pyqt6,panel]

sphinx:

  configuration: docs/conf.py

build_docs.sh

+1 −1
Original line number Diff line number Diff line 
SPHINX_APIDOC_OPTIONS=members,show-inheritance poetry run sphinx-apidoc -o docs/source src

#SPHINX_APIDOC_OPTIONS=members,show-inheritance poetry run sphinx-apidoc -o docs/source src

poetry run sphinx-build -M html docs docs/_build

docs/api_reference.rst

0 → 100644
+18 −0
Original line number Diff line number Diff line 
================

API Reference

================



---------------

Bindings

---------------



.. _api_bindings:



.. automodule:: nova.mvvm.trame_binding

   :members:



.. automodule:: nova.mvvm.pyqt6_binding

   :members:



.. automodule:: nova.mvvm.pyqt5_binding

   :members:

docs/conf.py

+1 −1
Original line number Diff line number Diff line
@@ -22,7 +22,7 @@ with open("../pyproject.toml", "rb") as toml_file: 
# -- General configuration ---------------------------------------------------

# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration



sys.path.insert(0, os.path.abspath("../src"))

sys.path.insert(0, os.path.abspath("../src/nova/mvvm"))



exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "__main__.py", "_internal"]

extensions = ["sphinx.ext.autodoc", "sphinx.ext.napoleon", "sphinx_rtd_theme"]

docs/core_concepts/data_binding.rst

0 → 100644
+86 −0
Original line number Diff line number Diff line 
Data Binding: The Heart of MVVM

-------------------------------



*Data binding* is a mechanism that allows the View and the ViewModel to

automatically synchronize their data. When the data in the ViewModel

changes, the View is automatically updated to reflect the changes.

Conversely, when the user interacts with the View (e.g., by entering

text in a field), the data in the ViewModel is automatically updated.



This data binding is what makes MVVM so powerful and allows for reactive

UIs. Instead of manually writing code to update the UI every time the

data changes, you simply bind the UI components to the data in the

ViewModel, and the updates happen automatically.





Data Binding with NOVA

----------------------



The **nova-mvvm** library greatly simplifies the data

synchronization between the components of an MVVM application and

provides support for user interfaces utilizing the Trame, PyQt, and

Panel graphical frameworks. The library provides several predefined

classes including TrameBinding, PyQtBinding, and PanelBinding to connect

UI components to model variables.



Here, we will focus on the TrameBinding class, but all three function similarly.



How to use TrameBinding

~~~~~~~~~~~~~~~~~~~~~~~



The initial step is to create a BindingInterface. A BindingInterface

serves as the foundational layer for how connections are made between

variables in the ViewModel and UI components in the View. Once a Trame

application has started, the :class:`nova.mvvm.interface.BindingInterface` can be created in the View

with:



.. code:: python



   bindingInterface = TrameBinding(self.server.state) # server is the Trame Server



After a BindingInterface has been created, variables must be added to

the interface via the interface's ``new_bind`` method. The ``new_bind``

method expects a variable that will be linked to a UI component, and an

optional callback method. The callback method is useful if there are

actions to be performed after updates to the UI. In the code snippet

below, we’ve passed the Binding Interface to the ViewModel. The

ViewModel adds the ``model`` variable to the binding interface. This

``new_bind`` method returns a :class:`nova.mvvm.interface.Communicator`. The ``Communicator`` is

an object which manages the binding and will be used to propgate

updates.



.. code:: python



   # Adding a binding to the Binding Interface, returns a Communicator

   self.config_bind = bindingInterface.new_bind(self.model)



The ``self.config_bind`` object is a ``Communicator`` and is used to

update the View. When the ViewModel needs to tell the View to perform an

Update, it calls the ``update_in_view`` method of the ``Communicator``.

For the ``self.config_bind`` object, the ViewModel would make a call

like below. It is common practice for the ViewModel to have a method

such as update_view, where ViewModel would update many objects. However,

there are also times when it is appropriate to only update a singular

object.



.. code:: python



   # Updating the UI connected to a binding.

   def update_view(self) -> None:

       self.config_bind.update_in_view(self.model)



We've seen how to create a BindingInterface, add a new binding, and how

to perform updates. We also need to connect our View components to the

Communicators. The Communicator class has a ``connect`` method. This

method accepts a callable object or a string. If you pass a callable

object, such as a method, that object will be called whenever the

binding's update_in_view method is called. In the example below, we

connect to the ``config_bind`` Communicator object that was created in

our ViewModel. When a string is passed to the connect method, that

string will be used as the unique name of our connector. In this

example, we pass in the string ``config`` but you are free to use any

string that is not already in use as a connector.



.. code:: python



   self.view_model.config_bind.connect("config")