Merge pull request #100 from beer-garden/Autobrew_Docs

Autobrew docs

.github/workflows/deploy.yml

@@ -48,24 +48,9 @@ jobs:
       - name: Upload Artifact
         uses: actions/upload-pages-artifact@v2
         with:
-          # upload entire directory
           path: 'public'
 
       - name: Deploy to GitHub Pages
         id: deployment
         uses: actions/deploy-pages@v2
 
-      # - name: Deploy to GitHub Pages
-      #   uses: crazy-max/ghaction-github-pages@v2
-      #   with:
-      #     target_branch: gh-pages
-      #     build_dir: public
-      #   env:
-      #     GITHUB_TOKEN: ${{ secrets.BUILDBOT_PAGES }}
-
-      # - name: Deploy to GitHub Pages
-      #   uses: crazy-max/ghaction-github-pages@v4
-      #   with:
-      #     target_branch: gh-pages
-      #     build_dir: public
-      #     dry_run: true

docs/plugins/plugin-developer-guide.adoc

@@ -8,6 +8,7 @@ These guides provide gentle introductions to plugin development. They are intend
 
 * link:../python/local-guide/[Python Plugin (Local)]
 * link:../python/remote-guide/[Python Plugin (Remote)]
+* link:../python/autobrew-guide/[Python Plugin (Autobrew)]
 
 TIP: If you want to know what Beer Garden is all about, find the answer in link:/docs/startup/what-is-beergarden/[What is Beer Garden?] If you're looking for a concise survey of plugin developer options, checkout the link:../plugin-syntax-quick-reference/[Plugin Developer Syntax Guide]
 
@@ -18,3 +19,5 @@ These guides will dive into some of the more specific ways you can develop plugi
 * How to run your plugin
 
 TIP: If you don't know the difference between remote and local plugins, please check the link:../local-vs-remote/[local vs remote plugins docs]
+
+TIP: If you have an external library that you want converted to a plugin, please checkout the Autobrew guide.

docs/plugins/python/_includes/beer-conf.adoc

@@ -1,7 +1,7 @@
 The `beer.conf` file explains how to configure your plugin. Let's explore the required `beer.conf` options.
 
 [source,python]
-.beer.conf (Required fields)
+.beer.conf (Required fields traditional Plugins)
 ----
 # Defines the system name of your plugin
 NAME = "my-plugin"
@@ -13,6 +13,17 @@ VERSION = "0.0.1"
 PLUGIN_ENTRY='main.py'
 ----
 
+[source,python]
+.beer.conf (Required fields for Autobrew)
+----
+# Autobrew module path
+AUTO_BREW_MODULE="my.module"
+
+# Autobrew class
+AUTO_BREW_CLASS="my_class"
+
+----
+
 In addition to the required fields, you may optionally provide other values to enhance your plugin. Each option is explained in more detail below.
 
 [source,python]
@@ -40,6 +51,12 @@ REQUIRES=['foo']
 
 # Additional Metadata you would like to add to the system
 METADATA = {'foo': 'bar'}
+
+# Autobrew ARG values to pass to AUTO_BREW_CLASS __init__
+AUTO_BREW_ARGS = ["foo","bar"]
+
+# Autobrew KWARG values to pass to AUTO_BREW_CLASS __init__
+AUTO_BREW_KWARGS = {"key","value"}
 ----
 
 === NAME
@@ -56,6 +73,14 @@ TIP: If you are in the process of developing a plugin, and want to change comman
 
 The `PLUGIN_ENTRY` entry in the `beer.conf` file is simply the python script that will execute `plugin.run()` That's really all there is to this.
 
+=== AUTO_BREW_MODULE
+
+The `AUTO_BREW_MODULE` entry is module on the pythonpath that the class object will be imported from for Autobrew to process
+
+=== AUTO_BREW_CLASS
+
+The `AUTO_BREW_CLASS` entry is class object within `AUTO_BREW_MODULE` for Autobrew to process
+
 === DESCRIPTION
 
 Again, a pretty straight-forward field. This is the system description that you'll see in the GUI/ReST API.
@@ -156,4 +181,112 @@ If you are writing a plugin that interacts with other plugins, then you should n
 REQUIRES=['foo']
 ----
 
+=== AUTO_BREW_ARGS
+
+The `AUTO_BREW_ARGS` field allows ARG values to be passed into the class initialization function
+
+The `AUTO_BREW_ARGS` entry plays along with the `INSTANCES` entry. If there are multiple instances and the `AUTO_BREW_ARGS` is a list, Beer Garden assumes that you want to pass the value of `AUTO_BREW_ARGS` to each and every instance that is defined in the `INSTANCES` section. For example:
+
+[source,python]
+----
+INSTANCES=['foo', 'bar']
+AUTO_BREW_ARGS=['arg1', 'arg2']
+AUTO_BREW_MODULE="my.module"
+AUTO_BREW_CLASS="my_class"
+----
+
+Tells Beer Garden to start two instances of your plugin via:
+
+[source,python]
+----
+my.module.my_class('arg1','arg2')
+my.module.my_class('arg1','arg2')
+----
+
+If you want to give different instances different arguments, you could do the following:
+
+[source,python]
+----
+INSTANCES = ['foo', 'bar', 'baz']
+AUTO_BREW_ARGS = {
+    'foo': ['arg1', 'arg2'],
+    'bar': ['arg3'],
+    'baz': []
+}
+----
+
+This will instruct Beer Garden to start 3 instances of your plugins via:
+
+[source,python]
+----
+my.module.my_class('arg1','arg2')
+my.module.my_class('arg3')
+my.module.my_class()
+----
+
+If you define your `AUTO_BREW_ARGS` as a dictionary, then there really is no need to define the `INSTANCES`. So the previous example and this example are functionally equivalent:
+
+[source,python]
+----
+PLUGIN_ARGS = {
+    'foo': ['arg1', 'arg2'],
+    'bar': ['arg3'],
+    'baz': []
+}
+----
+
+=== AUTO_BREW_KWARGS
+
+The `AUTO_BREW_KWARGS` field allows KARG values to be passed into the class initialization function.
+
+The `AUTO_BREW_KWARGS` entry plays along with the `INSTANCES` entry. If there are multiple instances and the `AUTO_BREW_KWARGS` is a list, Beer Garden assumes that you want to pass the value of `AUTO_BREW_KWARGS` to each and every instance that is defined in the `INSTANCES` section. For example:
+
+[source,python]
+----
+INSTANCES=['foo', 'bar']
+AUTO_BREW_KWARGS={"key_1","value_1", "key_2","value_2"}
+AUTO_BREW_MODULE="my.module"
+AUTO_BREW_CLASS="my_class"
+----
+
+Tells Beer Garden to start two instances of your plugin via:
+
+[source,python]
+----
+my.module.my_class(key_1='value_1', key_2='value_2')
+my.module.my_class(key_1='value_1', key_2='value_2')
+----
+
+If you want to give different instances different arguments, you could do the following:
+
+[source,python]
+----
+INSTANCES = ['foo', 'bar', 'baz']
+AUTO_BREW_KWARGS = {
+    'foo': {"key_1","value_1", "key_2","value_2"},
+    'bar': {"key_3","value_3"},
+    'baz': []
+}
+----
+
+This will instruct Beer Garden to start 3 instances of your plugins via:
+
+[source,python]
+----
+my.module.my_class(key_1='value_1', key_2='value_2')
+my.module.my_class(key_3='value_3')
+my.module.my_class()
+----
+
+If you define your `AUTO_BREW_KWARGS` as a dictionary, then there really is no need to define the `INSTANCES`. So the previous example and this example are functionally equivalent:
+
+[source,python]
+----
+AUTO_BREW_KWARGS = {
+    'foo': {"key_1","value_1", "key_2","value_2"},
+    'bar': {"key_3","value_3"},
+    'baz': []
+}
+----
+
 And that's it!

docs/plugins/python/autobrew-guide.adoc

@@ -0,0 +1,34 @@
+= Autobrew Plugins
+:page-layout: docs
+:includedir: _includes
+
+The goal of this section is to help you utilize an existing class as a Plugin.
+
+It is important to note that Autobrew is only supported by what is loaded on the pythonpath. The folder that contains the beer.conf that utilizes the Autobrew features is loaded onto the pythonpath.
+
+Autobrew will allow Beer Garden to evaluate the class object and automatically generate the Command and Parameter properties based off Type Hinting and Doc Strings.
+
+[TIP]
+.Pros of using Autobrew
+====
+If your client/system class does not require additional configurations when setting up the Plugin object, this feature can streamline your development.
+====
+
+== Exisiting Class Implementation
+
+Autobrew allows you to utilize existing class objects as a Plugin with no additional work. All it requires is the `beer.conf`!
+
+=== Unique beer.conf fields
+
+Autobrew supports all of the fields standard for beer.conf. The primary difference is that Autobrew has the additional fiels of:
+
+- AUTO_BREW_MODULE
+- AUTO_BREW_CLASS
+- AUTO_BREW_ARGS
+- AUTO_BREW_KARGS
+
+Allowing for the class to be intialized with static ARGS/KWARGS.
+
+== Plugin Configuration
+
+include::{includedir}/beer-conf.adoc[]