[Docs] Added an example for octoprint.comm.protocol.action handler

Used same example to illustrate hook handlers within mixin implementations.

docs/plugins/concepts.rst

@@ -135,54 +135,13 @@ If you want your hook handler to be an instance method of a mixin implementation
 need access to instance variables handed to your implementation via mixin invocations), you can get this work
 by using a small trick. Instead of defining it directly via ``__plugin_hooks__`` utilize the ``__plugin_init__``
 property instead, manually instantiate your implementation instance and then add its hook handler method to the
-``__plugin_hooks__`` property and itself to the ``__plugin_implementations__`` property. Example:
+``__plugin_hooks__`` property and itself to the ``__plugin_implementations__`` property. See the following example.
 
-.. code-block:: python
+.. onlineinclude:: https://raw.githubusercontent.com/OctoPrint/Plugin-Examples/master/custom_action_command.py
    :linenos:
-
-   # ...
-
-   class MyPluginImplementation(octoprint.plugin.StartupPlugin):
-
-       def __init__(self):
-           self._host = None
-           self._port = None
-
-       def on_startup(self, host, port):
-           self._host = host
-           self._port = port
-
-       def my_script_hook_handler(self, comm, script_type, script_name):
-           if not script_type == "gcode" or not script_name == "afterPrinterConnected":
-               # we only extend the gcode script afterPrinterConnected, ignore this
-               return None
-
-           if not self._host or not self._port:
-               # oops, we haven't started up yet, shouldn't even happen...
-               return None
-
-           # we only append something to the existing script, we don't prepend
-           prefix = None
-           postfix = ["M117 Hello World from %s:%d" % (self._host, self._port)]
-           return prefix, postfix
-
-   # ...
-
-   __plugin_implementations__ = []
-   __plugin_hooks__ = dict()
-
-   def __plugin_init__():
-       # this gets called when OctoPrint initializes the plugin, so let's create the
-       # instance of our main implementation ...
-       plugin = MyPluginImplementation()
-
-       # ... register it as implementation ...
-       global __plugin_implementations__
-       __plugin_implementations__ = [plugin]
-
-       # ... and its hook handler method as hook handler.
-       global __plugin_hooks__
-       __plugin_hooks__ = {"octoprint.comm.protocol.scripts": plugin.my_script_hook_handler}
+   :tab-width: 4
+   :caption: `custom_action_command.py <https://github.com/OctoPrint/Plugin-Examples/blob/master/custom_action_command.py>`_
+   :name: sec-plugin-concepts-hooks-example
 
 .. seealso::
 

docs/plugins/hooks.rst

@@ -3,6 +3,34 @@
 Available plugin hooks
 ======================
 
+.. _sec-plugins-hook-comm-protocol-action:
+
+octoprint.comm.protocol.action
+------------------------------
+
+.. py:function:: hook(comm_instance, line, action, *args, **kwargs)
+
+   React to a :ref:`action command <sec-features-action_commands>` received from the printer.
+
+   Hook handlers may use this to react to react to custom firmware messages. OctoPrint parses the received action
+   command ``line`` and provides the parsed ``action`` (so anything after ``// action:``) to the hook handler.
+
+   No returned value is expected.
+
+   **Example:**
+
+   Logs if the ``custom`` action (``// action:custom``) is received from the printer's firmware.
+
+   .. onlineinclude:: https://raw.githubusercontent.com/OctoPrint/Plugin-Examples/master/custom_action_command.py
+      :linenos:
+      :tab-width: 4
+      :caption: `custom_action_command.py <https://github.com/OctoPrint/Plugin-Examples/blob/master/custom_action_command.py>`_
+
+   :param object comm_instance: The :class:`~octoprint.util.comm.MachineCom` instance which triggered the hook.
+   :param str line: The complete line as received from the printer, format ``// action:<command>``
+   :param str action: The parsed out action command, so for a ``line`` like ``// action:some_command`` this will be
+       ``some_command``
+
 .. _sec-plugins-hook-comm-protocol-gcode:
 
 octoprint.comm.protocol.gcode
@@ -39,6 +67,8 @@ octoprint.comm.protocol.gcode
 
    .. onlineinclude:: https://raw.githubusercontent.com/OctoPrint/Plugin-Examples/master/rewrite_m107.py
       :linenos:
+      :tab-width: 4
+      :caption: `rewrite_m107.py <https://github.com/OctoPrint/Plugin-Examples/blob/master/rewrite_m107.py>`_
 
    :param object comm_instance: The :class:`~octoprint.util.comm.MachineCom` instance which triggered the hook.
    :param str cmd: The GCODE command for which the hook was triggered. This is the full command as taken either
@@ -49,25 +79,6 @@ octoprint.comm.protocol.gcode
    :return: A rewritten ``cmd``, a tuple of ``cmd`` and ``cmd_type`` or ``cmd``, ``cmd_type`` and ``with_checksum``
        or None to suppress sending of the ``cmd`` to the printer. See above for details.
 
-.. _sec-plugins-hook-comm-protocol-action:
-
-octoprint.comm.protocol.action
-------------------------------
-
-.. py:function:: hook(comm_instance, line, action, *args, **kwargs)
-
-   React to a :ref:`action command <sec-features-action_commands>` received from the printer.
-
-   Hook handlers may use this to react to react to custom firmware messages. OctoPrint parses the received action
-   command ``line`` and provides the parsed ``action`` (so anything after ``// action:``) to the hook handler.
-
-   No returned value is expected.
-
-   :param object comm_instance: The :class:`~octoprint.util.comm.MachineCom` instance which triggered the hook.
-   :param str line: The complete line as received from the printer, format ``// action:<command>``
-   :param str action: The parsed out action command, so for a ``line`` like ``// action:some_command`` this will be
-       ``some_command``
-
 .. _sec-plugins-hook-comm-protocol-scripts:
 
 octoprint.comm.protocol.scripts
@@ -87,10 +98,14 @@ octoprint.comm.protocol.scripts
    The returned entries may be either iterables of script lines or a string including newlines of the script lines (which
    will be split by the caller if necessary).
 
-   Example:
+   **Example:**
+
+   Appends an ``M117 OctoPrint connected`` to the configured ``afterPrinterConnected`` GCODE script.
 
    .. onlineinclude:: https://raw.githubusercontent.com/OctoPrint/Plugin-Examples/master/message_on_connect.py
       :linenos:
+      :tab-width: 4
+      :caption: `message_on_connect.py <https://github.com/OctoPrint/Plugin-Examples/blob/master/message_on_connect.py>`_
 
    :param MachineCom comm_instance: The :class:`~octoprint.util.comm.MachineCom` instance which triggered the hook.
    :param str script_type: The type of the script for which the hook was called, currently only "gcode" is supported here.

src/octoprint/util/virtual.py

@@ -269,6 +269,8 @@ class VirtualPrinter():
 			self.outgoing.put("// action:resume")
 		elif data == "action_disconnect":
 			self.outgoing.put("// action:disconnect")
+		elif data == "action_custom":
+			self.outgoing.put("// action:custom")
 		else:
 			try:
 				sleep_match = VirtualPrinter.sleep_regex.match(data)