merge docs.addons content into docs directory

Ticket:
Reviewed By:
Testing Done:

docs/source/addonsapiref.rst

@@ -0,0 +1,61 @@
+Documentation for the ifupdownaddons default addons modules
+***********************************************************
+
+address
+=======
+
+.. automodule:: address
+
+.. autoclass:: address
+   :members: run, get_ops
+
+
+bridge
+======
+
+.. automodule:: bridge
+
+.. autoclass:: bridge
+   :members: run, get_ops
+
+dhcp
+====
+
+.. automodule:: dhcp
+
+.. autoclass:: dhcp
+
+ethtool
+=======
+
+.. automodule:: ethtool
+
+.. autoclass:: ethtool
+
+ifenslave
+=========
+
+.. automodule:: ifenslave
+
+.. autoclass:: ifenslave
+
+mstpctl
+=======
+
+.. automodule:: mstpctl
+
+.. autoclass:: mstpctl
+
+usercmds
+========
+
+.. automodule:: usercmds
+
+.. autoclass:: usercmds
+
+vlan
+====
+
+.. automodule:: vlan
+
+.. autoclass:: vlan

docs/source/addonshelperapiref.rst

@@ -0,0 +1,44 @@
+Documentation for the ifupdownaddons package helper modules
+***********************************************************
+
+This package contains modules that provide helper methods
+for ifupdown2 addon modules to interact directly with tools
+like iproute2, brctl etc.
+
+
+bridgeutils
+===========
+
+Helper module to work with bridgeutil commands
+
+.. automodule:: bridgeutils
+
+.. autoclass:: brctl
+
+ifenslaveutil
+=============
+
+Helper module to interact with linux api to create bonds.
+Currently this is via sysfs.
+
+.. automodule:: ifenslaveutil
+
+.. autoclass:: ifenslaveutil
+
+dhclient
+========
+
+Helper module to interact with dhclient tools.
+
+.. automodule:: dhclient
+
+.. autoclass:: dhclient
+
+iproute2
+========
+
+Helper module to interact with iproute2 tools.
+
+.. automodule:: iproute2
+
+.. autoclass:: iproute2

docs/source/conf.py

@@ -17,6 +17,10 @@ import sys, os
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 sys.path.insert(0, os.path.abspath('../../ifupdown'))
+sys.path.append(os.path.abspath('../../addons'))
+sys.path.append(os.path.abspath('../../'))
+sys.path.append(os.path.abspath('../../ifupdownaddons'))
+sys.path.append(os.path.abspath('../../../ifupdown2'))
 
 # -- General configuration -----------------------------------------------------
 

docs/source/developmentcorner.rst

@@ -1,7 +1,7 @@
 Development Corner
 ==================
 
-getting started
+Getting started
 ---------------
 Unlike original ifupdown, all interface configuration is moved to external
 python modules. That includes inet, inet6 and dhcp configurations.
@@ -10,12 +10,63 @@ python modules. That includes inet, inet6 and dhcp configurations.
   infrastructure package, pls look at the apiref, documentation and code
   for python-ifupdown2
 
-* if you are looking at developing a new module, pls look at writing a addon
-  module in the python-ifupdown2-addons documentation
 
-Apiref
-------
+Writing a ifupdown2 addon module
+--------------------------------
+Addon modules are a nice way to add additional functionality to ifupdown2.
+Typically a new addon module will include support for a new network interface
+configuration which is not already supported by existing ifupdown2 addon
+modules.
+
+ifupdown2 addon modules are written in python. python-ifupdown2 package
+comes with default addon modules. All addon modules are installed under
+/usr/share/ifupdownaddons directory.
+
+The center of the universe for an addon module is the 'class iface' object
+exported by the python-ifupdown2 package.
+
+The iface object is modeled after an iface entry in the user provided network
+configuration file (eg. /etc/network/interfaces). For more details see
+the api reference for the iface class.
+
+ifupdown2 dynamically loads a python addon module. It expects the addon module
+to implement a few methods.
+
+* all addon modules must inherit from moduleBase class
+* the module must implement a class by the same name
+* the network interface object (class iface) and the operation to be performed
+  is passed to the modules. Operation can be any of 'pre-up', 'up', 'post-up',
+  'pre-down', 'down', 'post-down', 'query-check', 'query-running'.
+  The module can choose to support a subset or all operations.
+  In cases when the operation is query-check, the module must compare between
+  the given and running state and return the checked state of the object in
+  queryobjcur passed as argument to the run menthod.
+* the python addon class must provide a few methods:
+    * run() : method to configure the interface.
+    * get_ops() : must return a list of operations it supports.
+      eg: 'pre-up', 'post-down'
+    * get_dependent_ifacenames() : must return a list of interfaces the
+      supported interface is dependent on. This is used to build the
+      dependency list for sorting and executing interfaces in dependency order.
+    * if the module supports -r option to ifquery, ie ability to construct the
+      ifaceobj from running state, it can optionally implement the
+      get_dependent_ifacenames_running() method, to return the list of
+      dependent interfaces derived from running state of the interface.
+      This is different from get_dependent_ifacenames() where the dependent
+      interfaces are derived from the interfaces config file (provided by the
+      user).
+    * provide a dictionary of all supported attributes in the _modinfo
+      attribute. This is useful for syntax help and man page generation.
+
+python-ifupdown2 package also installs ifupdownaddons python package
+that contains helper modules for all addon modules.
+
+see example address handling module /usr/share/ifupdownaddons/address.py
+
+API reference
+-------------
 .. toctree::
    :maxdepth: 2
 
-   apiref.rst
+   addonsapiref.rst
+   addonshelperapiref.rst

docs/source/gettingstarted.rst

@@ -5,10 +5,10 @@ Prerequisites
 -------------
 * python-ifupdown2 is currently only tested on debian wheezy
 * python-ifupdown2 needs python version 2.6 or greater
-* build depends on: python-stdeb (for deb builds), python-docutils (for rst2man)
-* depends on python-gvgen package for printing interface graphs (this will be made optional in the future)
-* optional dependency for template engine: python-mako
-* python-ifupdown2 needs python-ifupdown2-addons to function correctly
+* Depends on: python-stdeb (for deb builds), python-docutils
+  (for rst2man), python-argcomplete, 'python-ipaddr'
+* Depends on python-gvgen package for printing interface graphs (this will be made optional in the future)
+* Optional dependency for template engine: python-mako
 
 
 Building
@@ -23,5 +23,5 @@ Installing
 ----------
 install generated python-ifupdown2-<ver>.deb
 
-$dpkg -i <python-ifupdown2-addons-<ver>.deb
+$dpkg -i <python-ifupdown2-<ver>.deb
 

docs/source/intro.rst

@@ -4,17 +4,28 @@ python-ifupdown2
 The python-ifupdown2 package provides the infrastructure for
 parsing /etc/network/interfaces file, loading, scheduling, template parsing,
 state management and interface dependency generation of interfaces.
+It dynamically loads python addon modules from /usr/share/ifupdownmodules.
+To remain compatible with other packages that depend on ifupdown, it also
+executes scripts under /etc/network/. To make the transition smoother, a
+python module under /usr/share/ifupdownmodules will override a script by
+the same name under /etc/network/. ifupdown2 publishes an interface object which
+is passed to all loadble python addon modules. All lodable modules are
+called for every interface declared in the /etc/network/interfaces file.
 
-It dynamically loads python modules from /usr/share/ifupdownmodules (provided
-by the python-ifupdown2-addons package). To remain compatible with other
-packages that depend on ifupdown, it also executes scripts under /etc/network/.
-To make the transition smoother, a python module under
-/usr/share/ifupdownmodules will override a script by the same name under
-/etc/network/.
+Addon modules are responsible for applying interface configuration.
+python-ifupdown2 ships with a set of default addon modules. Each module can
+declare its own set of supported attributes. Each module is passed the iface
+object (which is a representation of /etc/network/interfaces
+iface entry). Each module is also passed the operation to be performed.
 
-It publishes an interface object which is passed to all loadble python
-modules. For more details on adding a addon module, see the section on
-adding python modules.
+Example modules are /usr/share/ifupdownmodules/address.py,
+/usr/share/ifupdownmodules/bridge.py etc
+
+The order in which these modules are invoked is listed in
+/var/lib/ifupdownaddons/addons.conf. There is an ifaddon utility in the works
+to better manage the module ordering.
+
+For more details on adding an addon module, see the section on adding python
+modules. For details on how to write a module, see the api reference and
+development documentation.
 
-ifupdown2 module calls all modules for every interface declared in the
-/etc/network/interfaces file.