From bbd555a49b1f2d46dea77e57a244d909b4d51880 Mon Sep 17 00:00:00 2001
From: Andrew Bell <andrew.bell.ia@gmail.com>
Date: Wed, 30 Jun 2021 11:41:35 -0400
Subject: [PATCH] Update python filter doc.

---
 doc/stages/filters.python.rst | 19 ++++++++++++-------
 1 file changed, 12 insertions(+), 7 deletions(-)

diff --git a/doc/stages/filters.python.rst b/doc/stages/filters.python.rst
index 4a96044576..1892139154 100755
--- a/doc/stages/filters.python.rst
+++ b/doc/stages/filters.python.rst
@@ -185,19 +185,24 @@ for the in-scope :ref:`filters.python` :cpp:class:`pdal::Stage`.
        outs = ins
        return True
 
-Updating metadata
+Setting stage metadata
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The filter can update the global ``metadata`` dictionary as needed,
-define it as a
-**global** Python variable for the function's scope, and the updates will be
-reflected back into the pipeline from that stage forward.
+.. note::
+    The name of the output metadata variable has changed from ``metadata`` to ``out_metadata``.
+
+Stage metadata can be created by using the ``out_metadata`` dictionary **global** variable.
+The ``name`` key must be set. The type of the ``value`` can usually be inferred, but
+can be set to one of ``integer``, ``nonNegativeInteger``, ``double``, ``bounds``,
+``boolean``, ``spatialreference``, ``uuid`` or ``string``.
+
+Children may be set using the ``children`` key whose value is a list of dictionaries.
 
 .. code-block:: python
 
    def myfunc(ins,outs):
-     global metadata
-     metadata = {'name': 'root', 'value': 'a string', 'type': 'string', 'description': 'a description', 'children': [{'name': 'filters.python', 'value': 52, 'type': 'integer', 'description': 'a filter description', 'children': []}, {'name': 'readers.faux', 'value': 'another string', 'type': 'string', 'description': 'a reader description', 'children': []}]}
+     global out_metadata
+     out_metadata = {'name': 'root', 'value': 'a string', 'type': 'string', 'description': 'a description', 'children': [{'name': 'somekey', 'value': 52, 'type': 'integer', 'description': 'a filter description', 'children': []}, {'name': 'readers.faux', 'value': 'another string', 'type': 'string', 'description': 'a reader description', 'children': []}]}
      return True
 
 Passing Python objects