From 2d5773d11a0698f1cf421d7fc7c7d823be601124 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Sybren=20A=2E=20St=C3=BCvel?= <sybren@blender.org>
Date: Fri, 6 Mar 2020 14:28:54 +0100
Subject: Documentation: added bpy.msgbus description and examples

The `bpy.msgbus` namespace was not included in the documentation generation.
I've added it, and ported Campbell's examples from P563.
---
 doc/python_api/examples/bpy.msgbus.1.py | 44 +++++++++++++++++++++++++++++++++
 doc/python_api/examples/bpy.msgbus.2.py |  6 +++++
 doc/python_api/examples/bpy.msgbus.3.py |  5 ++++
 doc/python_api/sphinx_doc_gen.py        | 25 +++++++++++++++++++
 4 files changed, 80 insertions(+)
 create mode 100644 doc/python_api/examples/bpy.msgbus.1.py
 create mode 100644 doc/python_api/examples/bpy.msgbus.2.py
 create mode 100644 doc/python_api/examples/bpy.msgbus.3.py

diff --git a/doc/python_api/examples/bpy.msgbus.1.py b/doc/python_api/examples/bpy.msgbus.1.py
new file mode 100644
index 00000000000..21198471ffa
--- /dev/null
+++ b/doc/python_api/examples/bpy.msgbus.1.py
@@ -0,0 +1,44 @@
+"""
+The message bus system can be used to receive notifications when properties of
+Blender datablocks are changed via the data API.
+
+
+Limitations
+-----------
+
+The message bus system is triggered by updates via the RNA system. This means
+that the following updates will result in a notification on the message bus:
+
+- Changes via the Python API, for example ``some_object.location.x += 3``.
+- Changes via the sliders, fields, and buttons in the user interface.
+
+The following updates do **not** trigger message bus notifications:
+
+- Moving objects in the 3D Viewport.
+- Changes performed by the animation system.
+
+
+Example Use
+-----------
+
+Below is an example of subscription to changes in the active object's location.
+"""
+
+import bpy
+
+# Any Python object can act as the subscription's owner.
+owner = object()
+
+subscribe_to = bpy.context.object.location
+
+def msgbus_callback(*args):
+    # This will print:
+    # Something changed! (1, 2, 3)
+    print("Something changed!", args)
+
+bpy.msgbus.subscribe_rna(
+    key=subscribe_to,
+    owner=owner,
+    args=(1, 2, 3),
+    notify=msgbus_callback,
+)
diff --git a/doc/python_api/examples/bpy.msgbus.2.py b/doc/python_api/examples/bpy.msgbus.2.py
new file mode 100644
index 00000000000..5ac2187f7f9
--- /dev/null
+++ b/doc/python_api/examples/bpy.msgbus.2.py
@@ -0,0 +1,6 @@
+"""
+Some properties are converted to Python objects when you retrieve them. This
+needs to be avoided in order to create the subscription, by using
+``datablock.path_resolve("property_name", False)``:
+"""
+subscribe_to = bpy.context.object.path_resolve("name", False)
diff --git a/doc/python_api/examples/bpy.msgbus.3.py b/doc/python_api/examples/bpy.msgbus.3.py
new file mode 100644
index 00000000000..3af5660eff6
--- /dev/null
+++ b/doc/python_api/examples/bpy.msgbus.3.py
@@ -0,0 +1,5 @@
+"""
+It is also possible to create subscriptions on a property of all instances of a
+certain type:
+"""
+subscribe_to = (bpy.types.Object, "location")
diff --git a/doc/python_api/sphinx_doc_gen.py b/doc/python_api/sphinx_doc_gen.py
index 60058d5d17f..b47b59b473d 100644
--- a/doc/python_api/sphinx_doc_gen.py
+++ b/doc/python_api/sphinx_doc_gen.py
@@ -1756,6 +1756,7 @@ def write_rst_contents(basepath):
     app_modules = (
         "bpy.context",  # note: not actually a module
         "bpy.data",     # note: not actually a module
+        "bpy.msgbus",   # note: not actually a module
         "bpy.ops",
         "bpy.types",
 
@@ -1846,6 +1847,29 @@ def write_rst_ops_index(basepath):
         file.close()
 
 
+def write_rst_msgbus(basepath):
+    """
+    Write the rst files of bpy.msgbus module
+    """
+    if 'bpy.msgbus' in EXCLUDE_MODULES:
+        return
+
+    # Write the index.
+    filepath = os.path.join(basepath, "bpy.msgbus.rst")
+    file = open(filepath, "w", encoding="utf-8")
+    fw = file.write
+    fw(title_string("Message Bus (bpy.msgbus)", "="))
+    write_example_ref("", fw, "bpy.msgbus")
+    fw(".. toctree::\n")
+    fw("   :glob:\n\n")
+    fw("   bpy.msgbus.*\n\n")
+    file.close()
+
+    # Write the contents.
+    pymodule2sphinx(basepath, 'bpy.msgbus', bpy.msgbus, 'Message Bus')
+    EXAMPLE_SET_USED.add("bpy.msgbus")
+
+
 def write_rst_data(basepath):
     '''
     Write the rst file of bpy.data module
@@ -2000,6 +2024,7 @@ def rna2sphinx(basepath):
     write_rst_bpy(basepath)                 # bpy, disabled by default
     write_rst_types_index(basepath)         # bpy.types
     write_rst_ops_index(basepath)           # bpy.ops
+    write_rst_msgbus(basepath)              # bpy.msgbus
     pyrna2sphinx(basepath)                  # bpy.types.* and bpy.ops.*
     write_rst_data(basepath)                # bpy.data
     write_rst_importable_modules(basepath)
-- 
cgit v1.2.3