--- a/configurationengine/doc/api/public.rst Fri Mar 12 08:30:17 2010 +0200
+++ b/configurationengine/doc/api/public.rst Tue Aug 10 14:29:28 2010 +0300
@@ -1,147 +1,21 @@
-Public API
-**********
-Cone public API is the main interface of Cone.
-
-.. image:: cone_public_api.png
+.. _cone-public-api:
-
-.. module:: cone.public.api
- :platform: Unix, Windows
- :synopsis: Configuration interface.
-.. moduleauthor:: Teemu Rytkonen <teemu.rytkonen@nokia.com>
+Using ConE public API
+=====================
-Classes
--------
-.. class:: ObjectContainer
+Cone public API is the main interface of Cone.
- ObjectContainer is a base class for all Configuration related elements. It is container class for a tree structure,
- where it can contain other ObjectContainer objects. So basically you can create B-tree type of hiararchy with it.
-
- The main functionality of ObjectContainer is that **all children of an object container are accessible as members**
- of the container.
-
- .. _example_member_access:
-
- Example of ObjectContainer member access:
-
- ``objcontainer.configuration.get_name()``
-
+Developing with ConE API
+------------------------
+The ConE public API is described most accurately in the generated api documentation, which can be used as a reference guide.
- .. method:: _add(child)
-
- Add a ObjectContainer instance to this object. Checks with internal function :meth:`__supported_type__` if the given
- child is a supported class for this object.
-
- .. method:: _add_to_path(path,child)
-
- Add a ObjectContainer instance to a specific node under this object. It creates any missing nodes between this object
- and the path. For example __add_to_path__("foo.fii", obj), would create two nodes (foo and under it fii) if they are
- missing (Uses internal :meth:`__default_class__` to retrieve the class which is created in this case).
-
- .. method:: _remove(path)
-
- Remove a child from given path.
-
- .. method:: _get(path)
-
- get a child from given path.
-
- .. method:: _list()
-
- Get a list of names of immediate children of this ObjectContainer instance.
-
- .. method:: _objects()
-
- Get a list of immediate children objects of this ObjectContainer instance.
-
- .. method:: _traverse(filters)
-
- Get a list of children objects of this ObjectContainer instance, by filtering them with filters. This will cause a
- recursive _traverse method call to all children of the ObjectContainer.
-
- .. method:: _path(toparent=None)
-
- Return the path to this object up to the toparent object. When toparent=None this will
- return a full path to the object in the ObjectContainer hierarhcy.
-
- .. method:: _supported_type(obj)
-
- A method that is supposed to be overridden by the deriving classed if they need to change, which classes can be added
- under each class.
- Return True if the type of the obj is supported.
-
- .. method:: _default_class(obj)
-
- A method that is supposed to be overridden by the deriving classed if they need to change, what class is
- the default class that is created with __add_to_path__ when objects are missing.
- Return a class.
-
-
-.. class:: Base
+* See `Cone API epydoc <../epydoc/index.html>`_ reference guide.
- Base class for all :class:`~cone.public.api.Configuration` and its child objects.
-
- .. method:: get_ref()
-
- return the ref of this object.
-
- .. method:: get_namepace()
-
- return the namespace of this object.
-
-.. class:: Project
-
- Project is a container for Configuration's.
+Example usage of ConE public API
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+The below section is a example orientated desciption of ConE public api usage.
-.. class:: Configuration
-
- ConE Configuration is the main interface for all configuration related activities. It is the main interface of ConE
- itself as ConE is eventually a python interface to a configuration project.
-
-Configuration as a Container
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
- The Configuration instance itself in ConE is actually just a container for a bunch of different elements. These elements can practically be any elements that exist in a
- Configuration Project.
-
- * :class:`~cone.public.api.Configuration`
- * :class:`~cone.public.api.View`
- * :class:`~cone.public.api.Feature`
- * :class:`~cone.public.api.Resource`
- * :class:`~cone.public.plugin.Relation`
- * :class:`~cone.public.api.Data`
-
-.. class:: Feature
-
- Feature element is the base class for any Configurable item in a Configuration Project.
-
-.. class:: View
+.. toctree::
- A :class:`~cone.public.api.Configuration` can contain one or more View elements, which basically can define different type of tree structure of Feature elements that exist in the Configuration.
- A View element can contain :class:`~cone.public.api.Group` and :class:`FeaturePoxy` elements.
-
-.. class:: Group
-
- Group element can be child element of a :class:`~View`. It can include other Groups and :class:`~FeaturePoxy` elements to define a View hierarhcy.
-
-.. class:: FeatureProxy
-
- FeatureProxy element is a linking object inside View that has its own ref, name, etc but it basically just
- points to an actual :class:`Feature` instance.
-
-.. class:: Data
+ howto
- Data element defines a data value for a :class:`Feature` element. The Data elements can be defined in a
- :class:`Configuration` and single configurable :class:`Feature` can have multiple data definitions, in different
- configurations. The new definition always overrides the previous one. However the entire data definition hierarchy
- is stored and is available from the Cone API.
-
-.. class:: Storage
-
- Storage offers platform and persistence independent interface to store :class:`Resource` elements (data files,
- configuration files, etc).
-
-.. class:: Resource
-
- Resource is an instance of single storable element. Basically on normal filesystem this would be same as one file.
-