diff --git a/ifupdown2-addons/docs/source/addonshelperapiref.rst b/ifupdown2-addons/docs/source/addonshelperapiref.rst index 00d2e3b..01d9a41 100644 --- a/ifupdown2-addons/docs/source/addonshelperapiref.rst +++ b/ifupdown2-addons/docs/source/addonshelperapiref.rst @@ -6,8 +6,8 @@ for ifupdown2 addon modules to interact directly with tools like iproute2, brctl etc. -bridgeutils.py -============== +bridgeutils +=========== Helper module to work with bridgeutil commands @@ -15,8 +15,8 @@ Helper module to work with bridgeutil commands .. autoclass:: brctl -ifenslaveutil.py -================ +ifenslaveutil +============= Helper module to interact with linux api to create bonds. Currently this is via sysfs. @@ -25,8 +25,8 @@ Currently this is via sysfs. .. autoclass:: ifenslaveutil -dhclient.py -=========== +dhclient +======== Helper module to interact with dhclient tools. @@ -34,8 +34,8 @@ Helper module to interact with dhclient tools. .. autoclass:: dhclient -iproute2.py -=========== +iproute2 +======== Helper module to interact with iproute2 tools. diff --git a/ifupdown2-addons/docs/source/conf.py b/ifupdown2-addons/docs/source/conf.py index 26bcc16..e9ddb8d 100644 --- a/ifupdown2-addons/docs/source/conf.py +++ b/ifupdown2-addons/docs/source/conf.py @@ -1,7 +1,7 @@ # -*- coding: utf-8 -*- # -# ifupdown2 documentation build configuration file, created by -# sphinx-quickstart on Sun Jul 6 23:49:20 2014. +# ifupdown2-addons documentation build configuration file, created by +# sphinx-quickstart on Mon Jul 21 11:17:17 2014. # # This file is execfile()d with the current directory set to its containing dir. # @@ -16,15 +16,13 @@ import sys, os # If extensions (or modules to document with autodoc) are in another directory, # 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('.')) + sys.path.insert(0, os.path.abspath('../../addons')) sys.path.append(os.path.abspath('../../')) sys.path.append(os.path.abspath('../../ifupdownaddons')) sys.path.append(os.path.abspath('../../../ifupdown2')) -#sys.path.insert(0, os.path.abspath('/work/monster-03/roopa/cumulus-2.1-multimac/packages/ifupdown2-addons/pkg')) -#sys.path.append(os.path.abspath('/work/monster-03/roopa/cumulus-2.1-multimac/packages/ifupdown2/pkg')) -#sys.path.append(os.path.abspath('/work/monster-03/roopa/cumulus-2.1-multimac/packages/ifupdown2/')) - # -- General configuration ----------------------------------------------------- # If your documentation needs a minimal Sphinx version, state it here. @@ -32,7 +30,7 @@ sys.path.append(os.path.abspath('../../../ifupdown2')) # Add any Sphinx extension module names here, as strings. They can be extensions # coming with Sphinx (named 'sphinx.ext.*') or your custom ones. -extensions = ['sphinx.ext.autodoc', 'sphinx.ext.intersphinx', 'sphinx.ext.todo'] +extensions = ['sphinx.ext.autodoc'] # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] @@ -171,7 +169,7 @@ html_static_path = ['_static'] #html_file_suffix = None # Output file base name for HTML help builder. -htmlhelp_basename = 'ifupdown2doc' +htmlhelp_basename = 'ifupdown2-addonsdoc' # -- Options for LaTeX output -------------------------------------------------- @@ -190,7 +188,7 @@ latex_elements = { # Grouping the document tree into LaTeX files. List of tuples # (source start file, target name, title, author, documentclass [howto/manual]). latex_documents = [ - ('index', 'ifupdown2.tex', u'ifupdown2 Documentation', + ('index', 'ifupdown2-addons.tex', u'ifupdown2-addons Documentation', u'Roopa Prabhu', 'manual'), ] @@ -220,7 +218,7 @@ latex_documents = [ # One entry per manual page. List of tuples # (source start file, name, description, authors, manual section). man_pages = [ - ('index', 'ifupdown2', u'ifupdown2 Documentation', + ('index', 'ifupdown2-addons', u'ifupdown2-addons Documentation', [u'Roopa Prabhu'], 1) ] @@ -234,8 +232,8 @@ man_pages = [ # (source start file, target name, title, author, # dir menu entry, description, category) texinfo_documents = [ - ('index', 'ifupdown2', u'ifupdown2 Documentation', - u'Roopa Prabhu', 'ifupdown2', 'One line description of project.', + ('index', 'ifupdown2-addons', u'ifupdown2-addons Documentation', + u'Roopa Prabhu', 'ifupdown2-addons', 'One line description of project.', 'Miscellaneous'), ] @@ -247,7 +245,3 @@ texinfo_documents = [ # How to display URL addresses: 'footnote', 'no', or 'inline'. #texinfo_show_urls = 'footnote' - - -# Example configuration for intersphinx: refer to the Python standard library. -intersphinx_mapping = {'http://docs.python.org/': None} diff --git a/ifupdown2-addons/docs/source/developmentcorner.rst b/ifupdown2-addons/docs/source/developmentcorner.rst index f70b711..be5c563 100644 --- a/ifupdown2-addons/docs/source/developmentcorner.rst +++ b/ifupdown2-addons/docs/source/developmentcorner.rst @@ -3,31 +3,36 @@ Development Corner Writing a ifupdown2 addon module -------------------------------- -ifupdown2 addon modules are part of the python-ifupdown2 package. -They are installed under /usr/share/ifupdownaddons directory on the target box. +ifupdown2 addon modules are part of the python-ifupdown2-addons package. +They are installed under /usr/share/ifupdownaddons directory on the target +system. The center of the universe for an addon module is the 'class iface' object exported by the python-ifupdown2 package. -The iface object contains all config the user wanted. For more details see -the api refernce for the iface class. +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 invokes the addon module by invoking a few methods. And hence -it expects a few interfaces from the addon modules. +ifupdown2 dynamically loads a python addon module. It expects the addon module +to implement a few methods. -* all modules must inherit from moduleBase class -* the module should implement a class by the same name -* the interface object (class iface) and the operation to be performed is - passed to the modules. In cases when the operation is query-check, where - the module has to compare between the given and running state, the module - also takes an addional queryobjcur iface object -* the python addon class should provide 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 - interface is dependent on. This is used to build the dependency list - for sorting and executing interfaces in dependency order. + 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 @@ -38,13 +43,14 @@ it expects a few interfaces from the addon modules. * 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 a ifupdownaddons python package that -contains helper modules for all addon modules. +python-ifupdown2-addons package also installs ifupdownaddons python package +that contains helper modules for all addon modules. Its optional for the addon +module to use this package. see example address handling module /usr/share/ifupdownaddons/address.py -apiref ------- +API reference +------------- .. toctree:: :maxdepth: 2 diff --git a/ifupdown2-addons/docs/source/gettingstarted.rst b/ifupdown2-addons/docs/source/gettingstarted.rst index cf80113..e4345ca 100644 --- a/ifupdown2-addons/docs/source/gettingstarted.rst +++ b/ifupdown2-addons/docs/source/gettingstarted.rst @@ -3,21 +3,26 @@ Getting Started Prerequisites ------------- -* python-ifupdown2 is current only tested on a debian release wheezy or greater -* python-ifupdown2 needs python version 2.6 or greater +* python-ifupdown2-addons is currently only tested on debian wheezy +* python-ifupdown2-addons 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 soon) +* 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-addons has an install dependency on python-ifupdown2 Building -------- -git clone -cd ifupdown2-addons -./build.sh +$git clone ifupdown2 + +$cd ifupdown2/ifupdown2-addons + +$./build.sh Installing ---------- -install generated python-ifupdown2-addons-.deb +install generated python-ifupdown2-addons-.deb using dpkg + +$dpkg -i .deb diff --git a/ifupdown2-addons/docs/source/index.rst b/ifupdown2-addons/docs/source/index.rst index 4f557ac..27b6fd6 100644 --- a/ifupdown2-addons/docs/source/index.rst +++ b/ifupdown2-addons/docs/source/index.rst @@ -3,8 +3,8 @@ You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. -Welcome to ifupdown2's documentation! -===================================== +Welcome to ifupdown2-addons documentation! +========================================== Contents: ========= diff --git a/ifupdown2/docs/source/gettingstarted.rst b/ifupdown2/docs/source/gettingstarted.rst index 0de5829..16db725 100644 --- a/ifupdown2/docs/source/gettingstarted.rst +++ b/ifupdown2/docs/source/gettingstarted.rst @@ -3,20 +3,25 @@ Getting Started Prerequisites ------------- -* python-ifupdown2 is current only tested on a debian release wheezy or greater +* 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 soon) +* 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 Building -------- -git clone -cd ifupdown2 -./build.sh +$git clone ifupdown2 +$cd ifupdown2/ifupdown2 + +$./build.sh Installing ---------- install generated python-ifupdown2-.deb + +$dpkg -i .deb +