Documented that nothing should be defined outside the plugin class in…

… Python storage plugins (#867)

* Added warnings about defining stuff outside the plugin class in Python storage plugins.
* Added example help function to the storage plugin template.

doc/user_guide/storage_plugin.py

@@ -1,5 +1,14 @@
 """Template for Python storage plugins."""
 
+# NOTE:
+# Please, do not define any variables or functions outside the scope
+# of the plugin class.
+#
+# The reason for this requirement is that all plugins will be loaded
+# into the same shared scope within the built-in interpreter.
+# Hence, variables or functions outside the plugin class may interfere
+# with other plugins, resulting in hard-to-find bugs.
+
 
 class plugin_driver_name(dlite.DLiteStorageBase):
     """General description of the Python storage plugin."""
@@ -80,3 +89,11 @@ def to_bytes(cls, inst):
         Returns:
             The bytes (or bytearray) object that the instance is saved to.
         """
+
+    def _example_help_method(self, *args):
+        """Example help method.
+
+        If you need a help function, please make it a class method to
+        avoid possible naming conflicts with help functions in other
+        storage plugins.
+        """

doc/user_guide/storage_plugins.md

@@ -175,6 +175,16 @@ See the [Python storage plugin template] for how to write a Python storage plugi
 A complete example can be found in the [Python storage plugin example].
 
 
+:::{danger}
+**When writing a Python storage plugin, do not define any variables or functions outside the `DLiteStorageBase` subclass!**
+
+The reason for this requirement is that all plugins will be loaded into the same shared scope within the built-in interpreter.
+Hence, variables or functions outside the plugin class may interfere with other plugins, resulting in confusing and hard-to-find bugs.
+:::
+
+
+
+
 Working with storages from C and Fortran
 ----------------------------------------
 The C API for storages is documented in the [C reference manual].