Merge pull request #42123 from vutny/fix-master-utils-import

DOCS: describe importing custom util classes

doc/ref/configuration/minion.rst

@@ -1272,6 +1272,20 @@ A list of extra directories to search for Salt renderers
     render_dirs:
       - /var/lib/salt/renderers
 
+.. conf_minion:: utils_dirs
+
+``utils_dirs``
+---------------
+
+Default: ``[]``
+
+A list of extra directories to search for Salt utilities
+
+.. code-block:: yaml
+
+    utils_dirs:
+      - /var/lib/salt/utils
+
 .. conf_minion:: cython_enable
 
 ``cython_enable``

doc/topics/utils/index.rst

@@ -54,7 +54,7 @@ types like so:
 
             salt '*' mymodule.observe_the_awesomeness
         '''
-        print __utils__['foo.bar']()
+        return __utils__['foo.bar']()
 
 Utility modules, like any other kind of Salt extension, support using a
 :ref:`__virtual__ function <modules-virtual-name>` to conditionally load them,
@@ -81,11 +81,56 @@ the ``foo`` utility module with a ``__virtual__`` function.
     def bar():
         return 'baz'
 
+Also you could even write your utility modules in object oriented fashion:
+
+.. code-block:: python
+
+    # -*- coding: utf-8 -*-
+    '''
+    My utils module
+    ---------------
+
+    This module contains common functions for use in my other custom types.
+    '''
+
+    class Foo(object):
+
+        def __init__(self):
+            pass
+
+        def bar(self):
+            return 'baz'
+
+And import them into other custom modules:
+
+.. code-block:: python
+
+    # -*- coding: utf-8 -*-
+    '''
+    My awesome execution module
+    ---------------------------
+    '''
+
+    import mymodule
+
+    def observe_the_awesomeness():
+        '''
+        Prints information from my utility module
+
+        CLI Example:
+
+        .. code-block:: bash
+
+            salt '*' mymodule.observe_the_awesomeness
+        '''
+        foo = mymodule.Foo()
+        return foo.bar()
+
 These are, of course, contrived examples, but they should serve to show some of
 the possibilities opened up by writing utility modules. Keep in mind though
-that States still have access to all of the execution modules, so it is not
+that states still have access to all of the execution modules, so it is not
 necessary to write a utility module to make a function available to both a
-state and an execution module. One good use case for utililty modules is one
+state and an execution module. One good use case for utility modules is one
 where it is necessary to invoke the same function from a custom :ref:`outputter
 <all-salt.output>`/returner, as well as an execution module.
 

salt/loader.py

@@ -182,7 +182,7 @@ def minion_mods(
                             generated modules in __context__
 
     :param dict utils: Utility functions which should be made available to
-                            Salt modules in __utils__. See `utils_dir` in
+                            Salt modules in __utils__. See `utils_dirs` in
                             salt.config for additional information about
                             configuration.