Merge pull request #5586 from tbielawa/spiff_up_plugins

Spiff up the 'Developing Plugins' page

docsite/rst/developing_plugins.rst

@@ -14,14 +14,14 @@ as often.
 Connection Type Plugins
 -----------------------
 
-By default, ansible ships with a 'paramiko' SSH, native ssh (just called 'ssh'), and 'local' connection type, and an accelerated connection type named 'fireball' -- there are also some minor players like 'chroot' and 'jail'.  All of these can be used
+By default, ansible ships with a 'paramiko' SSH, native ssh (just called 'ssh'), 'local' connection type, and an accelerated connection type named 'fireball' (superseded in 1.3 by :doc:`playbooks_acceleration`) -- there are also some minor players like 'chroot' and 'jail'.  All of these can be used
 in playbooks and with /usr/bin/ansible to decide how you want to talk to remote machines.  The basics of these connection types
-are covered in the 'getting started' section.  Should you want to extend Ansible to support other transports (SNMP? Message bus?
+are covered in the :doc:`intro_getting_started` section.  Should you want to extend Ansible to support other transports (SNMP? Message bus?
 Carrier Pigeon?) it's as simple as copying the format of one of the existing modules and dropping it into the connection plugins
 directory.   The value of 'smart' for a connection allows selection of paramiko or openssh based on system capabilities, and chooses
 'ssh' if OpenSSH supports ControlPersist, in Ansible 1.2.1 an later.  Previous versions did not support 'smart'.
 
-More documentation on writing connection plugins is pending, though you can jump into lib/ansible/runner/connection_plugins and figure things out pretty easily.
+More documentation on writing connection plugins is pending, though you can jump into `lib/ansible/runner/connection_plugins <https://github.com/ansible/ansible/tree/devel/lib/ansible/runner/connection_plugins>`_ and figure things out pretty easily.
 
 .. _developing_lookup_plugins:
 
@@ -30,7 +30,7 @@ Lookup Plugins
 
 Language constructs like "with_fileglob" and "with_items" are implemented via lookup plugins.  Just like other plugin types, you can write your own.
 
-More documentation on writing connection plugins is pending, though you can jump into lib/ansible/runner/lookup_plugins and figure
+More documentation on writing connection plugins is pending, though you can jump into `lib/ansible/runner/lookup_plugins <https://github.com/ansible/ansible/tree/devel/lib/ansible/runner/lookup_plugins>`_ and figure
 things out pretty easily.
 
 .. _developing_vars_plugins:
@@ -42,7 +42,7 @@ Playbook constructs like 'host_vars' and 'group_vars' work via 'vars' plugins.
 data into ansible runs that did not come from an inventory, playbook, or command line.  Note that variables
 can also be returned from inventory, so in most cases, you won't need to write or understand vars_plugins.
 
-More documentation on writing connection plugins is pending, though you can jump into lib/ansible/inventory/vars_plugins and figure
+More documentation on writing connection plugins is pending, though you can jump into `lib/ansible/inventory/vars_plugins <https://github.com/ansible/ansible/tree/devel/lib/ansible/inventory/vars_plugins>`_ and figure
 things out pretty easily.
 
 If you find yourself wanting to write a vars_plugin, it's more likely you should write an inventory script instead.
@@ -52,9 +52,9 @@ If you find yourself wanting to write a vars_plugin, it's more likely you should
 Filter Plugins
 --------------
 
-If you want more Jinja2 filters available in a Jinja2 template (filters like to_yaml and to_json are provided by default), they can be extended by writing a filter plugin.  Most of the time, when someone comes up with an idea for a new filter they would like to make available in a playbook, we'll just include them in 'core.py' instead.  
+If you want more Jinja2 filters available in a Jinja2 template (filters like to_yaml and to_json are provided by default), they can be extended by writing a filter plugin.  Most of the time, when someone comes up with an idea for a new filter they would like to make available in a playbook, we'll just include them in 'core.py' instead.
 
-Jump into lib/ansible/runner/filter_plugins/ for details.
+Jump into `lib/ansible/runner/filter_plugins/ <https://github.com/ansible/ansible/tree/devel/lib/ansible/runner/filter_plugins>`_ for details.
 
 .. _developing_callbacks:
 
@@ -68,27 +68,34 @@ Callbacks are one of the more interesting plugin types.  Adding additional callb
 Examples
 ++++++++
 
-Example callbacks are shown `in github in the callbacks directory <https://github.com/ansible/ansible/tree/devel/plugins/callbacks>_`.
+Example callbacks are shown in `plugins/callbacks <https://github.com/ansible/ansible/tree/devel/plugins/callbacks>`_.
 
-The 'log_plays' callback is an example of how to intercept playbook events to a log file, and the 'mail' callback sends email
-when playbooks complete.
+The `log_plays
+<https://github.com/ansible/ansible/blob/devel/plugins/callbacks/log_plays.py>`_
+callback is an example of how to intercept playbook events to a log
+file, and the `mail
+<https://github.com/ansible/ansible/blob/devel/plugins/callbacks/mail.py>`_
+callback sends email when playbooks complete.
 
-The 'osx_say' callback provided is particularly entertaining -- it will respond with computer synthesized speech on OS X in relation
-to playbook events, and is guaranteed to entertain and/or annoy coworkers.
+The `osx_say
+<https://github.com/ansible/ansible/blob/devel/plugins/callbacks/osx_say.py>`_
+callback provided is particularly entertaining -- it will respond with
+computer synthesized speech on OS X in relation to playbook events,
+and is guaranteed to entertain and/or annoy coworkers.
 
 .. _configuring_callbacks:
 
 Configuring
 +++++++++++
 
-To active a callback drop it in a callback directory as configured in ansible.cfg.
+To active a callback drop it in a callback directory as configured in :ref:`ansible.cfg <callback_plugins>`.
 
 .. _callback_development:
 
 Development
 +++++++++++
 
-More information will come later, though see the source of any of the existing callbacks and you should be able to get started quickly.  
+More information will come later, though see the source of any of the existing callbacks and you should be able to get started quickly.
 They should be reasonably self explanatory.
 
 .. _distributing_plugins:
@@ -124,4 +131,3 @@ In addition, plugins can be shipped in a subdirectory relative to a top-level pl
        The development mailing list
    `irc.freenode.net <http://irc.freenode.net>`_
        #ansible IRC chat channel
-