DOC: Add documentation about current getters support

docs/advanced.md

@@ -0,0 +1,29 @@
+# Advanced
+----------
+
+## Returning Values
+
+Communication with the IPython Kernel is asynchronous, which means that  running Python code blocks any comm messages until the Python code is done. With regards to ITKWidgets this means that getter functions do not "just work" - the Python code cannot complete until the comm message has resolved with the response and the message cannot resolve until the code has completed. This creates a deadlock that prevents the kernel from progressing. This has been a [documented issue](https://github.com/ipython/ipykernel/issues/65) for many years.
+
+Libraries like [ipython_blocking](https://github.com/kafonek/ipython_blocking) and [jupyter-ui-poll](https://github.com/Kirill888/jupyter-ui-poll) have made efforts to address this issue and their approaches have been a great source of inspiration for the custom solution that we have chosen for ITKWidgets.
+
+Our current solution prevents deadlocks but requires that getters be requested in one cell and resolved in another. For example:
+
+```python
+viewer = view(image)
+```
+```python
+bg_color = viewer.get_background_color()
+print(bg_color)
+```
+would simply become:
+
+```python
+viewer = view(image)
+```
+```python
+bg_color = viewer.get_background_color()
+```
+```python
+print(bg_color)
+```

docs/index.md

@@ -23,4 +23,5 @@ quick_start_guide.rst
 deployments.rst
 integrations.rst
 development.rst
+advanced.rst
 ```