Merge pull request #87 from beer-garden/update-plugin-docs

Update plugin creation docs

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

@@ -42,33 +42,33 @@ REQUIRES=['foo']
 METADATA = {'foo': 'bar'}
 ----
 
-=== NAME entry
+=== NAME
 
 The `NAME` entry is pretty straight-forward. It is the system name that will be used to identify your system.
 
-=== VERSION entry
+=== VERSION
 
 The `VERSION` entry is supposed to be a semantic-version. That means something that looks like `X.X.X` where `X` can be any number. The version is important to Beer Garden, and it will not let you upload two systems with the same version that has different command/parameters.
 
 TIP: If you are in the process of developing a plugin, and want to change commands or parameters, you can name your version `X.X.X.dev0` which will allow you to overwrite command and parameters in place.
 
-=== PLUGIN_ENTRY entry
+=== PLUGIN_ENTRY
 
 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.
 
-=== DESCRIPTION entry
+=== DESCRIPTION
 
 Again, a pretty straight-forward field. This is the system description that you'll see in the GUI/ReST API.
 
-=== METADATA entry
+=== METADATA
 
 The `METADATA` field allows you to associate METADATA with your system. This can be helpful for service-discovery type information or anything else specific with your system that you would like programmatically discoverable.
 
-=== DISPLAY_NAME entry
+=== DISPLAY_NAME
 
 This is the name the system will appear under in the GUI.
 
-=== ENVIRONMENT entry
+=== ENVIRONMENT
 
 If there is some reason you cannot or do not want to pass your information in through the command line or through a file of your choosing, you can choose to set variables in your environment using the `ENVIRONMENT` portion of the `beer.conf` file. The `ENVIRONMENT` entry is simply a dictionary that contains all the ENVIRONMENT Variables you want. Please note that all ENVIRONMENT variables will be converted to strings before they are included. You can also utilize other environment variables that you know are set. For example, the `BG_PLUGIN_PATH`:
 
@@ -82,11 +82,11 @@ ENVIRONMENT={
 
 Pretty Cool, right?
 
-=== INSTANCES entry
+=== INSTANCES
 
 Whether or not you know it, your plugin will have instances. If you do not provide Beer Garden with the `INSTANCES` key, then it will assume you only want one instance of the plugin and will create it with a plugin with a single instance named `default`. Entries in the `INSTANCES` section will be validated against entries in <<plugin_args>> section.
 
-=== PLUGIN_ARGS entry
+=== PLUGIN_ARGS
 
 If you want something to be easily changeable, this is something you may be interested in. Often times, this can be used as a way to pass in a configuration file. For Example:
 
@@ -147,7 +147,7 @@ PLUGIN_ARGS = {
 }
 ----
 
-=== REQUIRES entry
+=== REQUIRES
 
 If you are writing a plugin that interacts with other plugins, then you should note this dependency in the `REQUIRES` field. Simply, if you are writing a plugin 'bar' that relies on foo add:
 

docs/plugins/python/_includes/hello-world-client.adoc

@@ -1,18 +1,16 @@
 [source,python]
-.plugin.py
+.main.py
 ----
-from brewtils import command, system
+from brewtils import Plugin, command
 
-@system # <1>
 class HelloWorldClient(object):
 
-    @command <2>
+    @command <1>
     def hello_world(self):
         greeting = "Hello, World!"
 
         print(greeting)
 
         return greeting
 ----
-<1> The `@system` decorator marks this class as a Beer Garden plugin.
-<2> The `@command` decorator marks this method as a Command that's part of the enclosing System.
+<1> The `@command` decorator marks this method as a Command that's part of the enclosing Client.

docs/plugins/python/_includes/hello-world-local-entry-point.adoc

@@ -1,15 +1,33 @@
 [source,python]
-.plugin.py
+.main.py
 ----
-from brewtils import Plugin
+from brewtils import Plugin, command
+
+
+class HelloWorldClient(object):
+
+    @command <1>
+    def say_hello(self):
+        greeting = "Hello, World!"
+
+        print(greeting)
+
+        return greeting
 
-# Your implementation of the client goes here
 
 def main():
     client = HelloWorldClient()
-    plugin = Plugin(client)
+
+    plugin = Plugin(
+        client=client,
+        name="hello-world", <2>
+        version="1.0",
+        description="Say hello"
+    )
     plugin.run()
 
 if __name__ == "__main__":
     main()
 ----
+<1> The `@command` decorator marks this method as a Command that's part of the enclosing Client.
+<2> The values defined here determine how the plugin is listed in the UI.

docs/plugins/python/_includes/hello-world-remote-entry-point.adoc

@@ -1,14 +1,13 @@
 [source,python]
 .plugin.py
 ----
-from brewtils import command, system, Plugin
+from brewtils import Plugin, command
 
 
-@system
 class HelloWorldClient(object):
 
-    @command
-    def hello_world(self):
+    @command <1>
+    def say_hello(self):
         greeting = "Hello, World!"
 
         print(greeting)
@@ -20,11 +19,11 @@ def main():
     client = HelloWorldClient()
 
     plugin = Plugin(
-        client,
-        name='hello-world',
-        version='1.0.0',
-        description='My First Plugin',
-        bg_host="<HOST>",
+        client=client,
+        name="hello-world", <2>
+        version="1.0.0",
+        description="My First Plugin",
+        bg_host="<HOST>", <3>
         bg_port="<PORT>",
         ssl_enabled=<SSL_ENABLED>,
     )
@@ -34,5 +33,8 @@ def main():
 if __name__ == "__main__":
     main()
 ----
+<1> The `@command` decorator marks this method as a Command that's part of the enclosing Client.
+<2> The values defined here determine how the plugin is listed in the UI.
+<3> Be sure to replace `<HOST>`, `<PORT>`, and `<SSL_ENABLED>` with appropriate values for your garden.
 
 To review what's happening here: we added an import `Plugin` at the top of our file and created a standard main method. In that method we created a `HelloWorldClient` object and a `Plugin` object. Notice that when we create the `Plugin` we pass it the client and some additional parameters. Don't worry too much about the additional paramters - we'll cover them later.

docs/plugins/python/local-guide.adoc

@@ -19,10 +19,6 @@ Plugins are just classes with methods that you would like to expose. This sectio
 
 Use your favorite text editor and open up a file called `main.py` and add the following:
 
-include::{includedir}/hello-world-client.adoc[]
-
-Once we have the client, we now need to create our entry point. Let's open back up the previous file and add the following:
-
 include::{includedir}/hello-world-local-entry-point.adoc[]
 
 === Configure your plugin
@@ -39,18 +35,16 @@ Now that you've written your code and `beer.conf`, you'll need to find a way to
 [source,python]
 .setup.py
 ----
-import sys
-import os
-from setuptools import setup, find_packages
+from setuptools import find_packages, setup
 
-requirements = ['brewtils']
+requirements = ["brewtils"]
 
 setup_args = {
-  'name'             : 'my_plugin',
-  'description'      : 'My Cool Plugin that does stuff',
-  'version'          : '1.0.0',
-  'pacakges'         : find_packages(exclude=['test','test.*']),
-  'install_requires' : requirements
+    "name": "hello_world",
+    "description": "Say hello",
+    "version": "1.0",
+    "packages": find_packages(exclude=["test", "test.*"]),
+    "install_requires": requirements,
 }
 
 setup(**setup_args)
@@ -82,12 +76,12 @@ Take your `tar.gz` file, and copy it to the plugins directory of Beer Garden. Th
 
 [source]
 ----
-cp dist/my-plugin-0.0.1.tar.gz /opt/beer-garden/plugins/
+cp dist/hello_world-1.0.tar.gz /opt/beer-garden/plugins/
 cd /opt/beer-garden/plugins/
-tar -zxvf my-plugin-0.0.1.tar.gz
+tar -zxvf hello_world-1.0.tar.gz
 ----
 
-Now go to the Beer Garden GUI under `Administration -> Systems Management` and click `Rescan System Directory` in the top right. This will instruct Beer Garden to scan the plugins directory for new plugins and start them. You should see your plugin appear. Once it is up, you can go to `Systems` then your system and see the command `hello_world`! Click `Make it Happen!` then `Make Request` to see your plugin in action.
+Now go to the Beer Garden GUI under `Admin -> Systems` and click `Rescan Plugin Directory` in the top right. This will instruct Beer Garden to scan the plugins directory for new plugins and start them. You should see your plugin appear. Once it is up, you can go to the `Systems` page, click `Explore` next to the `hello-world` System, and see the command `say_hello`! Click `Make it Happen!` then `Make Request` to see your plugin in action.
 
 That's it!
 
@@ -111,19 +105,7 @@ The only thing in this directory structure that should look non-standard is the
 
 === beer.conf
 
-The `beer.conf` file is a minimal configuration file that specifies to Beer Garden how to configure and start up the plugin. The beer.conf file has minimal options. Below is an expanded beer.conf file that explains all the possible values.
-
-
-    NAME = "my-plugin"                           # The name of your plugin
-    DISPLAY_NAME = "My Plugin"                   # The name shown in the GUI
-    VERSION = "0.0.1"                            # The version of your plugin
-    DESCRIPTION = "My plugin does cool stuff"    # A description of your plugin
-    PLUGIN_ENTRY = 'main.py'                     # Defines way to run the plugin
-    INSTANCES = ["i1", "i2"]                     # The instances to define
-    PLUGIN_ARGS = ['arg1']                       # Command line arguments to each instance
-    ENVIRONMENT = {'MY_PASSWORD':'sup3r$ecret'}  # Environment variables
-    REQUIRES = ['foo']                           # Defines relationship to 'foo' plugin
-
+The `beer.conf` file is a minimal configuration file that specifies to Beer Garden how to configure and start up the plugin. More information is available below in the <<plugin-configuration>> section.
 
 === MANIFEST.in
 
@@ -161,7 +143,7 @@ include::{includedir}/exceptions.adoc[]
 
 For Local plugins, Beer Garden will attempt to make decent decisions about where it should log. For example, if Beer Garden is configured to log to `STDOUT` or `STDERR` then your plugin will log there as well. If, however, Beer Garden is configured to log to a file (the default behavior for RPMs), then it will give each unique plugin its own log file. If you would like to log, you can either print to `STDOUT` or `STDERR`. The `LocalPlugin` will take care of everything else.
 
-INFO: Use STDOUT or STDERR for logging
+NOTE: Use STDOUT or STDERR for logging
 
 You can use the python logging to log to stderr with your own format if you'd like via:
 

docs/plugins/python/remote-guide.adoc

@@ -19,10 +19,6 @@ This section will take you through setting up a simple Hello, World example.
 
 Plugins are basically just classes that you would like to expose over the network. So let's create a simple, and classic "Hello, World!" example. Use your favorite text editor and open up a file called `plugin.py` and add the following:
 
-include::{includedir}/hello-world-client.adoc[]
-
-Once we have the client, we now need to create our entry point. Let's open back up the previous file and add the following:
-
 include::{includedir}/hello-world-remote-entry-point.adoc[]
 
 That's all the code you need!
@@ -31,13 +27,13 @@ That's all the code you need!
 
 Run the plugin like this:
 
-    python main.py
+    python plugin.py
 
 It will start up and print some logging showing the plugin registering with Beer Garden. Congratulations! You've just deployed your first plugin!
 
 === Use the code
 
-At this point you should see your plugin on the `Available Systems` page in `Brew View`. Click the big blue `Explore hello_world commands` button to see a list of all commands available for the Plugin you made.
+At this point you should see your plugin on the `Systems` page in `Beer Garden`. Click the big blue `Explore` button next to `hello-world` to see a list of all commands available for the Plugin you made.
 
 Since we only defined one command as part of this tutorial the only command listed should be the `say_hello` command. Click the `Make it Happen!` button to go to the page for that command.
 
@@ -52,13 +48,12 @@ If you didn't catch those changes on the first try, don't worry. Use the `Pour i
 NOTE: This command doesn't have any parameters, but for commands that do the `Pour it Again` button will default them to exactly how they were for the original request.
 
 === Stop the code
-The best way to stop a plugin is to use the Systems Management page to send a stop message. In `Brew View` find the `Systems Management` option under the `Administration` menu. Then click the stop icon next to the `hello-world` listing.
+The best way to stop a plugin is to use the Systems Management page to send a stop message. In `Beer Garden` find the `Systems` option under the `Admin` menu. Then click the stop icon next to the `hello-world` listing.
 
-You should see your plugin log that it has terminated and stop executing, and if you go to the main page in `Brew View` you should see the `hello-world` plugin is 'STOPPED'.
+You should see your plugin log that it has terminated and stop executing, and if you go to the `Admin -> Systems` page in `Beer Garden` you should see the `hello-world` plugin is 'STOPPED'.
 
 NOTE: You can also use Ctrl-c to stop the plugin from the terminal. This works, but it doesn't tell Beer Garden that the plugin is stopping. You'll still see the plugin terminate and stop executing, but the status in `Brew View` will still be 'RUNNING'. After a short period the status will change to 'UNRESPONSIVE'.
 
-
 == Exception Handling
 include::{includedir}/exceptions.adoc[]
 

docs/startup/installation-guides/rhel.adoc

@@ -168,6 +168,6 @@ tar -zxvf my-plugin-0.0.1.tar.gz
 Edit any configuration files necessary for the plugin. You can start the new plugin through the GUI:
 
 * Navigate to the beer-garden GUI
-* Select Administration -> Systems Management
-* Click "Rescan System Directory"
+* Select Admin -> Systems
+* Click "Rescan Plugin Directory"
 * You should see your plugin appear!