Permalink
Browse files

working on docs

	modified:   .gitignore
	modified:   botoform/plugins/__init__.py
	modified:   botoform/plugins/create.py
	modified:   botoform/plugins/destroy.py
	modified:   botoform/plugins/dump.py
	modified:   botoform/plugins/lock.py
	modified:   botoform/plugins/repl.py
	modified:   botoform/plugins/unlock.py
	modified:   botoform/util.py
	modified:   docs/source/reference/enriched/index.rst
	modified:   docs/source/reference/plugins/index.rst
	modified:   docs/source/schema/index.rst
  • Loading branch information...
Russell Ballestrini
Russell Ballestrini committed Jan 17, 2016
1 parent 41b050c commit 0be07adb867b3c33458fdf2ea95e8a286f78298b
View
@@ -23,3 +23,6 @@ env3
# Files running bf command could create.
*.pem
+
+# temporary editor files.
+*.swp
@@ -0,0 +1,28 @@
+class ClassPlugin(object):
+ """This is a :ref:`class plugin` for the :ref:`bf` tool."""
+
+ @staticmethod
+ def setup_parser(parser):
+ """
+ Accepts a subparser and attaches additional arguments and flags.
+
+ :param parser: An ArgumentParser sub parser.
+ Reference: https://docs.python.org/3/library/argparse.html
+
+ :returns: None
+ """
+ pass
+
+ @staticmethod
+ def main(args, evpc=None):
+ """
+ The main logic for this plugin.
+
+ :params args: The parsed arguments and flags from the CLI.
+ :param evpc: An instance of :meth:`botoform.enriched.vpc.EnrichedVPC`.
+
+ :returns: None
+ """
+ pass
+
+
View
@@ -4,13 +4,27 @@
from botoform.util import key_value_to_dict
+from botoform.plugins import ClassPlugin
+
from argparse import SUPPRESS
-class Create(object):
- """Create a new VPC and related services, modeled from YAML template."""
+class Create(ClassPlugin):
+ """
+ Create a new VPC and related services, modeled from YAML template.
+
+ This is a :ref:`class plugin` for the :ref:`bf` tool.
+ """
@staticmethod
def setup_parser(parser):
+ """
+ Accepts a subparser and attaches additional arguments and flags.
+
+ :param parser: An ArgumentParser sub parser.
+ Reference: https://docs.python.org/3/library/argparse.html
+
+ :returns: None
+ """
parser.add_argument('--skip-evpc', default=True, help=SUPPRESS)
parser.add_argument('cidrblock',
help='The CIDR block to use when creating VPC.')
@@ -26,8 +40,15 @@ def setup_parser(parser):
)
@staticmethod
- def main(args, evpc):
- """Output a list of instance names. (example botoform plugin)"""
+ def main(args, evpc=None):
+ """
+ Creates a new VPC and related services, modeled from a YAML template.
+
+ :param args: The parsed arguments and flags from the CLI.
+ :param evpc: :meth:`botoform.enriched.vpc.EnrichedVPC` or None.
+
+ :returns: None
+ """
context_vars = key_value_to_dict(args.vars)
aws_tags = key_value_to_dict(args.tags)
loader = ConfigLoader(context_vars = context_vars)
@@ -1,4 +1,11 @@
def destroy(args, evpc):
- """Destroy a VPC and related resources and services."""
+ """
+ Destroy a VPC and related resources and services.
+
+ :param args: The parsed arguments and flags from the CLI.
+ :param evpc: An instance of :meth:`botoform.enriched.vpc.EnrichedVPC`.
+
+ :returns: None
+ """
evpc.terminate()
View
@@ -1,15 +1,29 @@
from botoform.util import output_formatter
def instances(args, evpc):
- """Output a list of instance names."""
+ """
+ Output instance roles to standard out in :ref:`Botoform Schema <schema reference>`.
+
+ :param args: The parsed arguments and flags from the CLI.
+ :param evpc: An instance of :meth:`botoform.enriched.vpc.EnrichedVPC`.
+
+ :returns: instance_roles to standard out in :ref:`Botoform Schema <schema reference>`.
+ """
if args.identifiers or args.roles or args.exclude:
instances = evpc.find_instances(args.identifiers, args.roles, args.exclude)
else:
instances = evpc.instances
print(output_formatter(map(str, instances), args.output_format))
def security_groups(args, evpc):
- """Output Security Groups in a Botoform compatible format."""
+ """
+ Output Security Groups to standard out in :ref:`Botoform Schema <schema reference>`.
+
+ :param args: The parsed arguments and flags from the CLI.
+ :param evpc: An instance of :meth:`botoform.enriched.vpc.EnrichedVPC`.
+
+ :returns: security_groups to standard out in :ref:`Botoform Schema <schema reference>`.
+ """
sgs = {}
for sg in evpc.security_groups.all():
sgs[sg.group_name] = []
@@ -44,6 +58,11 @@ def security_groups(args, evpc):
}
class Dump(object):
+ """
+ Dump AWS resourses as :ref:`Botoform Schema <schema reference>`.
+
+ This is a :ref:`class plugin` for the :ref:`bf` tool.
+ """
@staticmethod
def setup_parser(parser):
View
@@ -1,4 +1,11 @@
def lock(args, evpc):
- """Lock all instances in VPC to prevent termination."""
+ """
+ Lock all instances in VPC to prevent termination.
+
+ :param args: The parsed arguments and flags from the CLI.
+ :param evpc: An instance of :meth:`botoform.enriched.vpc.EnrichedVPC`.
+
+ :returns: None
+ """
evpc.lock_instances()
View
@@ -23,7 +23,15 @@
def REPL(args, evpc):
"""
Open an interactive REPL (read-eval-print-loop) with access to evpc object
- """
+
+ :param args: The parsed arguments and flags from the CLI.
+ :param evpc: An instance of :meth:`botoform.enriched.vpc.EnrichedVPC`.
+
+ :subcommand aliases: cli and shell
+
+ :returns:
+ Interactive shell with evpc :meth:`botoform.enriched.vpc.EnrichedVPC`.
+ """
msg = BANNER.format(evpc.id, evpc.name, evpc.region_name)
if interpreter == 'bpython':
bpython.embed(locals_ = locals(), banner = msg)
@@ -1,4 +1,11 @@
def unlock(args, evpc):
- """Lock all instances in VPC to prevent termination."""
+ """
+ Unock all instances in VPC to allow termination.
+
+ :param args: The parsed arguments and flags from the CLI.
+ :param evpc: An instance of :meth:`botoform.enriched.vpc.EnrichedVPC`.
+
+ :returns: None
+ """
evpc.unlock_instances()
View
@@ -2,6 +2,7 @@
import json
import boto3
+# dynamic nonsequential hostnames.
import hashlib
import humanhash
@@ -14,6 +14,7 @@ We use composition to provide many helper attributes and methods.
.. contents::
+
vpc.py
=======
@@ -4,30 +4,30 @@
plugins
#######
-.. note:: For working examples see the `plugins <https://github.com/russellballestrini/botoform/tree/master/botoform/plugins>`_ directory.
-
You may extend the :ref:`bf` tool by writing a plugin.
+.. note:: For working examples see the `plugins <https://github.com/russellballestrini/botoform/tree/master/botoform/plugins>`_ directory.
+
A :ref:`bf` plugin must take one of two forms:
#. `function plugin`_
#. `class plugin`_
-All :ref:`bf` subcommands have been implemented in this way.
+Regardless of the form of plugin you choose, your plugin project's
+*setup.py* must define an `entry point`_ in the ``botoform.plugins`` group.
+The name of the `entry point`_ will be the subcommand on the CLI.
-In your plugin project's *setup.py* create an `entry point`_ in the
-``botoform.plugins`` group.
+All :ref:`bf` subcommands have been implemented in this way.
-The name of the `entry point`_ will be the subcommand on the CLI.
.. _function plugin:
-Function plugin
+function plugin
===============
-This example shows how to write a function plugin.
+This example shows how to write a `function plugin`_.
-In this case we will define a ``destroy`` `entry point`_ and subcommand.
+In this case we will define an `entry point`_ and subcommand named ``destroy``.
*setup.py*:
@@ -39,9 +39,9 @@ In this case we will define a ``destroy`` `entry point`_ and subcommand.
]
}
-The `entry point`_ ``destroy`` points to the location of the function *destroy*.
+The `entry point`_ named ``destroy`` declares the path to the ``destroy`` function.
-The function needs to accept *args* and the *evpc* object.
+The function must accept an *args* object and an *evpc* object, for example:
*mybotoform/plugins/destroy.py*:
@@ -51,12 +51,15 @@ The function needs to accept *args* and the *evpc* object.
"""Destroy a VPC and related resources and services."""
evpc.terminate()
+
.. _class plugin:
-Class Plugin
+class plugin
============
-If additional args and flags need to be defined, the plugin must take this form:
+This example shows how to write a `class plugin`_.
+
+Only choose this form if your subcommand needs additional args or flags.
*setup.py*:
@@ -97,45 +100,71 @@ setup_parser:
main:
main logic for this plugin.
-Terms
-=====
-.. _entry point:
+.. _core plugins:
-entry point:
- An entry point is a Python object identified in a project's ``setup.py`` file.
- The object is referenced by group and name to make it discoverable.
- This means that another Python application can search the installed software.
- During the search, often the entry point group filters relevant objects.
+core plugins
+============
- Botoform uses this method to allow plugins to load at run time.
+The Botoform :ref:`bf` tool ships with many core plugins and subcommands.
-Core Plugins
-============
-All :ref:`bf` subcommands are plugins.
+botoform.plugins.create
+-------------------------
.. automodule:: botoform.plugins.create
:members:
:undoc-members:
+botoform.plugins.destroy
+-------------------------
+
.. automodule:: botoform.plugins.destroy
:members:
:undoc-members:
+
+botoform.plugins.lock
+-------------------------
+
.. automodule:: botoform.plugins.lock
:members:
:undoc-members:
+
+botoform.plugins.unlock
+-------------------------
+
.. automodule:: botoform.plugins.unlock
:members:
:undoc-members:
+
+botoform.plugins.dump
+-------------------------
+
.. automodule:: botoform.plugins.dump
:members:
:undoc-members:
+
+botoform.plugins.repl
+-------------------------
+
.. automodule:: botoform.plugins.repl
:members:
:undoc-members:
+
+terms
+=====
+
+.. _entry point:
+
+entry point:
+ An entry point is a Python object identified in a project's ``setup.py`` file.
+ The object is referenced by group and name to make it discoverable.
+ This means that another Python application can search the installed software.
+ During the search, often the entry point group filters relevant objects.
+
+ Botoform uses this method to allow plugins to load at run time.
@@ -1,3 +1,4 @@
+.. _schema reference:
Schema Reference
################

0 comments on commit 0be07ad

Please sign in to comment.