Add get_thing_states to action docs

Author: rwb27

docs/source/actions.rst

@@ -67,6 +67,32 @@ a long time to run, or it may simply be a helpful debugging aid.
 
 See :mod:`.logs` for details of how this is implemented.
 
+.. _get_thing_states:
+
+Collecting metadata
+--------------------
+It's relatively common to want to collect metadata that summarises all of the `.Thing`
+instances in the current server. It's good practice to embed this kind of metadata in
+data files or images, and so LabThings provides a convenience function to collect it.
+`.ThingServerInterface.get_thing_states` will return a mapping of `.Thing` names to
+metadata dictionaries, suitable for embedding in a data file. The metadata dictionaries
+are generated by the ``thing_state`` property of each `.Thing`\ .
+
+The metadata can be accessed through the Thing-Server Interface, which is a property
+of the `.Thing`\ :
+
+.. code-block:: python
+
+    import json
+    import labthings_fastapi as lt
+
+    class MyThing(lt.Thing):
+        @lt.action
+        def gather_metadata(self) -> str:
+            """Return metadata about all Things, as a string."""
+            metadata_dict = self._thing_server_interface.get_thing_states()
+            return json.dumps(metadata_dict)
+
 .. _action_cancellation:
 
 Cancelling actions