updating the plugin system docs

Author: joseph-flinn

docs/plugin_system.rst

@@ -34,28 +34,14 @@ JSON
 Developing a Plugin
 -------------------
 
-.. module:: tmuxp 
-
-Plugin API
-^^^^^^^^^^
-
-.. automethod:: tmuxp.plugin.TmuxpPluginInterface.before_workspace_builder
-.. automethod:: tmuxp.plugin.TmuxpPluginInterface.on_window_create
-.. automethod:: tmuxp.plugin.TmuxpPluginInterface.after_window_finished
-.. automethod:: tmuxp.plugin.TmuxpPluginInterface.before_script
-.. automethod:: tmuxp.plugin.TmuxpPluginInterface.reattach
-
-
-Example Plugin
---------------
-
-Tmuxp expects all plugins to be class within a python submodule named 
+tmuxp expects all plugins to be class within a python submodule named 
 ``plugin`` that is within a python module that is installed in the local 
 python environment. A plugin interface is provided by tmuxp to inherit. 
 
 `poetry`_ is the chosen python package manager for tmuxp. It is highly 
 suggested to use it when developing tmuxp plugins; however, ``pip`` will work 
-just as well.
+just as well. Only one of the configuration files is needed for the packaging tool that the
+package developer desides to use. 
 
 .. code-block:: bash
 
@@ -66,6 +52,7 @@ just as well.
     ├── pyproject.toml  # Poetry's module configuration file
     └── setup.py        # pip's module configuration file
 
+
 The `plugin.py` file could contain something like the following:
 
 .. code-block:: python
@@ -75,6 +62,13 @@ The `plugin.py` file could contain something like the following:
 
     class MyTmuxpPlugin(TmuxpPluginInterface):
         def __init__(self):
+            """
+            Currently optional.
+
+            In the current version of the plugin interface, the __init__
+            isn't being utilized. However, it does provide a space for 
+            later additions to the interface.
+            """
             super.__init__(self)
 
         def before_workspace_builder(self, session):
@@ -87,9 +81,19 @@ The `plugin.py` file could contain something like the following:
 Once this plugin is installed in the local python environment, it can be used
 in a configuration file like the following:
 
-.. code-block: yaml
+.. code-block:: yaml
 
     session_name: plugin example
     plugins:
     - my_plugin_module.plugin.MyTmuxpPlugin
     # ... the rest of your config
+
+
+Plugin API
+----------
+
+.. automethod:: tmuxp.plugin.TmuxpPluginInterface.before_workspace_builder
+.. automethod:: tmuxp.plugin.TmuxpPluginInterface.on_window_create
+.. automethod:: tmuxp.plugin.TmuxpPluginInterface.after_window_finished
+.. automethod:: tmuxp.plugin.TmuxpPluginInterface.before_script
+.. automethod:: tmuxp.plugin.TmuxpPluginInterface.reattach

tmuxp/plugin.py

@@ -9,65 +9,70 @@ def before_workspace_builder(self, session):
         """
         Provide a session hook previous to creating the workspace.
 
+        This runs after the session has been created but before any of 
+        the windows/panes/commands are entered.
+
         Parameters
         ----------
         session : :class:`libtmux.Session`
             session to hook into
-
-        Notes
-        -----
-        This runs after the session has been created but before any of 
-        the windows/panes/commands are entered.
         """
         pass
 
     def on_window_create(self, window):
         """
-        Provide a window hook previous to creating the window.
+        Provide a window hook previous to doing anything with a window.
+
+        This runs runs before anything is created in the windows, like panes.
 
         Parameters
         ----------
         window: :class:`libtmux.Window`
             window to hook into
-        
-        Notes
-        -----
-        This runs runs before anything is created in the windows, like panes.
         """
         pass
 
     def after_window_finished(self, window):
         """
         Provide a window hook after creating the window.
 
+        This runs after everything has been created in the window, including
+        the panes and all of the commands for the panes. It also runs after the
+        ``options_after`` has been applied to the window.
+
         Parameters
         ----------
         window: :class:`libtmux.Window`
             window to hook into
-
-        Notes
-        -----
-        This runs after everything has been created in the window, including
-        the paes and all of the commands for the panes. It also runs after the
-        ``options_after`` have been applied to the window.
         """
         pass
 
     def before_script(self, session):
         """
         Provide a session hook after the workspace has been built.
 
+        This runs after the workspace has been loaded with ``tmuxp load``. It
+        augments instead of replaces the ``before_script`` section of the
+        configuration. 
+
+        This hook provides access to the LibTmux.session object for any 
+        behavior that would be used in the ``before_script`` section of the 
+        configuration file that needs access directly to the session object.
+        This runs after the workspace has been loaded with ``tmuxp load``. 
+        
+        The hook augments, rather than replaces, the ``before_script`` section 
+        of the configuration. While it is possible to do all of the 
+        ``before_script`` configuration in this function, if a shell script 
+        is currently being used for the configuration, it would be cleaner to 
+        continue using the script in the ``before_section``.
+        
+        If changes to the session need to be made prior to 
+        anything being built, please use ``before_workspace_builder`` instead.
+
         Parameters
         ----------
         session : :class:`libtmux.Session`
             session to hook into
-
-        Notes
-        -----
-        This runs after the workspace has been loaded with ``tmuxp load``. It
-        augments instead of replaces the ``before_script`` section of the
-        configuration. If changes to the session need to be made prior to 
-        anything being built, please use ``before_workspace_builder`` instead.
         """
         pass