Merge branch 'newlodel' of git.labocleo.org:lodel2 into newlodel

lodel/editorial_model/__init__.py

@@ -1 +1,50 @@
-__author__ = 'roland'
+##@defgroup lodel2_em Editorial Model
+#@brief Data organisation description
+
+##@package lodel.editorial_model
+#@brief Editorial model package
+#
+#The editorial model defines objects with fields. This objects will be later
+#manipulated via @ref lodel.leapi "LeAPI"
+
+##@page lodel2_em_page Editorial Model
+#@ingroup lodel2_em
+#
+#@section lodel2_em_what What is an editorial model ?
+#
+#The editorial model is a kind of entity-relationship model describing
+#editorial objects.
+#
+#@warning The lodel.editorial_model package does not contains code executed by
+#instances. The editorial model is used to generate python code named 
+#@ref lodel2_leapi "LeAPI" and the package contains Classes that made easy
+#the Em manipulation
+#
+# @subsection lodel2_em_class EmClass
+#
+#An editorial object is named @ref components.EmClass "EmClass" for "Editorial
+# Model Class". A class is characterized by a uniq name a 
+#@ref lodel2_datasources "Datasource", a group, an optionnal parent EmClass and
+#the @ref components.EmField "EmFields" it contains.
+#
+#@par Example
+#<code>An "Article" is an EmClass with "article" as name, the EmClass "Text" as
+#parent etc...</code>
+#
+# @subsection lodel2_em_field EmField
+#
+#@ref components.EmClass "EmClasses" contains 
+#@ref components.EmField "EmFields". An EmField as a name (uniq in the EmClass)
+# and is associated to a @ref lodel2_datahandlers "DataHandler" specification.
+#
+# @subsection lodel2_em_group EmGroup
+#
+#@ref components.EmClass "EmClasses" and @ref components.EmField "EmFields"
+#are in @ref components.EmGroup "EmGroups". EmGroups represent a consistent
+#EditorialModel part that can be activated or deactivated.
+#
+#@par Example
+#<pre>EmGroup "authors" contains the EmClass authors and all its EmField
+# + "written_by" EmField (a reference field on "Author" EmClass) in the EmClass
+#"Text"</pre>
+#

lodel/editorial_model/components.py

@@ -1,5 +1,9 @@
 #-*- coding: utf-8 -*-
 
+##@package lodel.editorial_model.components
+#@brief Defines all @ref lodel2_em "EM" components
+#@ingroup lodel2_em
+
 import itertools
 import warnings
 import copy
@@ -14,6 +18,7 @@ from lodel.leapi.leobject import CLASS_ID_FIELDNAME
 ##@brief Abstract class to represent editorial model components
 # @see EmClass EmField
 # @todo forbid '.' in uid
+#@ingroup lodel2_em
 class EmComponent(object):
     
     ##@brief Instanciate an EmComponent
@@ -46,6 +51,7 @@ class EmComponent(object):
 
 
 ##@brief Handles editorial model objects classes
+#@ingroup lodel2_em
 class EmClass(EmComponent):
     
     ##@brief Instanciate a new EmClass
@@ -206,6 +212,7 @@ class EmClass(EmComponent):
 
 
 ##@brief Handles editorial model classes fields
+#@ingroup lodel2_em
 class EmField(EmComponent):
 
     ##@brief Instanciate a new EmField
@@ -259,6 +266,7 @@ class EmField(EmComponent):
         ).digest(), byteorder='big')
 
 ##@brief Handles functionnal group of EmComponents
+#@ingroup lodel2_em
 class EmGroup(object):
         
     ##@brief Create a new EmGroup

lodel/editorial_model/model.py

@@ -13,6 +13,7 @@ from lodel.editorial_model.exceptions import *
 from lodel.editorial_model.components import EmClass, EmField, EmGroup
 
 ##@brief Describe an editorial model
+#@ingroup lodel2_em
 class EditorialModel(object):
     
     ##@brief Create a new editorial model

lodel/leapi/__init__.py

@@ -1 +1,208 @@
-__author__ = 'roland'
+##@defgroup lodel2_leapi LeAPI
+#@brief Lodel2 Editorial API
+#
+#Provide access to datas via objects as defined in the Editorial Model
+
+##@package lodel.leapi
+#@brief Lodel2 Editorial API
+#
+# Defines an API to access to objects as described by 
+#@ref lodel.editorial_model "Editorial Model"
+
+##@page lodel2_leapi_page LeAPI
+#@ingroup lodel2_leapi
+#
+# @section lodel2_leapi_base LeAPI (Lodel Editorial API)
+#
+# LeAPI is an API that provide access to datas as defined in an 
+#@ref lodel2_em "Editorial Model".
+#
+#@subsection lodel2_leapi_gen LeAPI dynamic code & LeFactory
+#
+#LeAPI python code is programmaticaly generated by 
+#@ref lodel.leapi.lefactory "LeFactory". LeFactory generates 
+#@ref lodel.leapi.leobject.LeObject "LeObject" child classes.
+#
+#@par Example
+#<pre>
+#
+#    from lodel.leapi.leobject import LeObject
+#    from lodel.leapi.datahandlers.base_classes import DataField
+#    from lodel.plugin.hooks import LodelHook
+#
+#    class Abstract_Object(LeObject):
+#        _abstract = True
+#        _fields = None
+#        _uid = []
+#        _ro_datasource = None
+#        _rw_datasource = None
+#        _datasource_name = 'default'
+#        _child_classes = None
+#
+#
+#    class User(LeObject):
+#        _abstract = False
+#        _fields = None
+#        _uid = ['id']
+#        _ro_datasource = None
+#        _rw_datasource = None
+#        _datasource_name = 'default'
+#        _child_classes = None
+#
+#
+#    class Object(Abstract_Object):
+#        _abstract = True
+#        _fields = None
+#        _uid = ['lodel_id']
+#        _ro_datasource = None
+#        _rw_datasource = None
+#        _datasource_name = 'default'
+#        _child_classes = None
+#
+#
+#    class Entry(Object):
+#        _abstract = True
+#        _fields = None
+#        _uid = ['lodel_id']
+#        _ro_datasource = None
+#        _rw_datasource = None
+#        _datasource_name = 'default'
+#        _child_classes = None
+#
+#
+#    class Entitie(Object):
+#        _abstract = True
+#        _fields = None
+#        _uid = ['lodel_id']
+#        _ro_datasource = None
+#        _rw_datasource = None
+#        _datasource_name = 'default'
+#        _child_classes = None
+#
+#
+#    class Person(Object):
+#        _abstract = False
+#        _fields = None
+#        _uid = ['lodel_id']
+#        _ro_datasource = None
+#        _rw_datasource = None
+#        _datasource_name = 'default'
+#        _child_classes = None
+#
+#    class Text(Entitie):
+#        _abstract = True
+#        _fields = None
+#        _uid = ['lodel_id']
+#        _ro_datasource = None
+#        _rw_datasource = None
+#        _datasource_name = 'default'
+#        _child_classes = None
+#
+#
+#    class Publication(Entitie):
+#        _abstract = False
+#        _fields = None
+#        _uid = ['lodel_id']
+#        _ro_datasource = None
+#        _rw_datasource = None
+#        _datasource_name = 'default'
+#        _child_classes = None
+#
+#    Abstract_Object._set__fields({})
+#    Abstract_Object._child_classes = (Section, Text, Object, Entry, Collection, Text_Person, Entitie, Indextheme, Person, Indexabs, Publication, Subsection,)
+#    User._set__fields({
+#            'firstname': DataField.from_name('varchar')(**{ 'internal': False }), 
+#            'lastname': DataField.from_name('varchar')(**{ 'internal': False }), 
+#            'classname': DataField.from_name('LeobjectSubclassIdentifier')(**{ 'internal': True }), 
+#            'login': DataField.from_name('varchar')(**{ 'internal': True, 'uniq': True }), 
+#            'id': DataField.from_name('uniqid')(**{ 'internal': True }), 
+#            'password': DataField.from_name('password')(**{ 'internal': False })})
+#    User._child_classes = tuple()
+#    Object._set__fields({
+#            'date_update': DataField.from_name('datetime')(**{ 'now_on_update': True, 'internal': True }), 
+#            'lodel_id': DataField.from_name('uniqid')(**{ 'internal': True }), 
+#            'help_text': DataField.from_name('text')(**{ 'internal': True }), 
+#            'date_create': DataField.from_name('datetime')(**{ 'internal': True, 'now_on_create': True })})
+#    Object._child_classes = (Section, Text, Entry, Collection, Text_Person, Entitie, Indextheme, Person, Indexabs, Publication, Subsection,)
+#    Entry._set__fields({
+#            'date_update': DataField.from_name('datetime')(**{ 'now_on_update': True, 'internal': True }), 
+#            'lodel_id': DataField.from_name('uniqid')(**{ 'internal': True }), 
+#            'help_text': DataField.from_name('text')(**{ 'internal': True }), 
+#            'date_create': DataField.from_name('datetime')(**{ 'internal': True, 'now_on_create': True })})
+#    Entry._child_classes = tuple()
+#    Entitie._set__fields({
+#            'date_update': DataField.from_name('datetime')(**{ 'now_on_update': True, 'internal': True }), 
+#            'lodel_id': DataField.from_name('uniqid')(**{ 'internal': True }), 
+#            'help_text': DataField.from_name('text')(**{ 'internal': True }), 
+#            'date_create': DataField.from_name('datetime')(**{ 'internal': True, 'now_on_create': True })})
+#    Entitie._child_classes = (Section, Text, Text_Person, Collection, Publication, Subsection,)
+#    Person._set__fields({
+#            'date_update': DataField.from_name('datetime')(**{ 'now_on_update': True, 'internal': True }), 
+#            'firstname': DataField.from_name('varchar')(**{  }), 
+#            'lodel_id': DataField.from_name('uniqid')(**{ 'internal': True }), 
+#            'linked_texts': DataField.from_name('list')(**{ 'nullable': True, 'default': None, 'allowed_classes': [Text], 'back_reference': (Text, 'linked_persons') }), 
+#            'help_text': DataField.from_name('text')(**{ 'internal': True }), 
+#            'lastname': DataField.from_name('varchar')(**{  }), 
+#            'fullname': DataField.from_name('Concat')(**{ 'field_list': ['firstname', 'lastname'], 'immutable': True }), 
+#            'classname': DataField.from_name('LeobjectSubclassIdentifier')(**{ 'internal': True }), 
+#            'alias': DataField.from_name('set')(**{ 'nullable': True, 'default': None, 'allowed_classes': [Person] }), 
+#            'date_create': DataField.from_name('datetime')(**{ 'internal': True, 'now_on_create': True })})
+#    Person._child_classes = tuple()
+#    Text._set__fields({
+#            'date_update': DataField.from_name('datetime')(**{ 'now_on_update': True, 'internal': True }), 
+#            'subtitle': DataField.from_name('varchar')(**{ 'nullable': True, 'default': None }), 
+#            'lodel_id': DataField.from_name('uniqid')(**{ 'internal': True }), 
+#            'help_text': DataField.from_name('text')(**{ 'internal': True }), 
+#            'linked_persons': DataField.from_name('list')(**{ 'nullable': True, 'default': None, 'allowed_classes': [Person], 'back_reference': (Person, 'linked_texts') }), 
+#            'indexes': DataField.from_name('list')(**{ 'nullable': True, 'default': None, 'allowed_classes': [Indexabs], 'back_reference': (Indexabs, 'texts') }), 
+#            'title': DataField.from_name('varchar')(**{ 'nullable': True }), 
+#            'date_create': DataField.from_name('datetime')(**{ 'internal': True, 'now_on_create': True })})
+#    Text._child_classes = (Section, Subsection,)
+#    Publication._set__fields({
+#            'date_update': DataField.from_name('datetime')(**{ 'now_on_update': True, 'internal': True }), 
+#            'classname': DataField.from_name('LeobjectSubclassIdentifier')(**{ 'internal': True }), 
+#            'lodel_id': DataField.from_name('uniqid')(**{ 'internal': True }), 
+#            'collection': DataField.from_name('link')(**{ 'back_reference': (Collection, 'publications') }), 
+#            'help_text': DataField.from_name('text')(**{ 'internal': True }), 
+#            'date_create': DataField.from_name('datetime')(**{ 'internal': True, 'now_on_create': True })})
+#    Publication._child_classes = tuple()
+#
+#    #List of dynamically generated classes
+#    dynclasses = [Abstract_Object, User, Object, Entry, Entitie, Person, Indexabs, Text, Publication, Collection, Indextheme, Text_Person, Section, Subsection]
+#    #Dict of dynamically generated classes indexed by name
+#    dynclasses_dict = {'Abstract_Object': Abstract_Object, 'User': User, 'Object': Object, 'Entry': Entry, 'Entitie': Entitie, 'Person': Person, 'Indexabs': Indexabs, 'Text': Text, 'Publication': Publication, 'Collection': Collection, 'Indextheme': Indextheme, 'Text_Person': Text_Person, 'Section': Section, 'Subsection': Subsection}
+#
+#
+#    ##@brief Return a dynamically generated class given it's name
+#    #@param name str : The dynamic class name
+#    #@return False or a child class of LeObject
+#    def name2class(name):
+#        if name not in dynclasses_dict:
+#            return False
+#        return dynclasses_dict[name]
+#
+#
+#    ##@brief Return a dynamically generated class given it's name
+#    #@note Case insensitive version of name2class
+#    #@param name str
+#    #@retrun False or a child class of LeObject
+#    def lowername2class(name):
+#        name = name.lower()
+#        new_dict = {k.lower():v for k,v in dynclasses_dict.items()}
+#        if name not in new_dict:
+#            return False
+#        return new_dict[name]
+#
+#
+#    ##@brief Trigger dynclasses datasources initialisation
+#    @LodelHook("lodel2_plugins_loaded")
+#    def lodel2_dyncode_datasources_init(self, caller, payload):
+#        for cls in dynclasses:
+#            cls._init_datasources()
+#        from lodel.plugin.hooks import LodelHook
+#        LodelHook.call_hook("lodel2_dyncode_loaded", __name__, dynclasses)
+#
+#
+#
+#</pre>
+#

lodel/leapi/leobject.py

@@ -116,7 +116,7 @@ class LeObject(object):
     #   Fields datas handling methods   #
     #-----------------------------------#
 
-    ##@brief @property True if LeObject is initialized else False
+    ##@brief Property method True if LeObject is initialized else False
     @property
     def initialized(self):
         return self.__is_initialized

lodel/leapi/query.py

@@ -454,7 +454,6 @@ the relational filter %s"
                     msg %= (ref_class.__name__, ref_field)
                     logger.debug(msg)
         if len(ref_dict) == 0:
-            print(ref_classes, 'DEBUG')
             return NameError(   "No field named '%s' in referenced objects [%s]"
                                 % (ref_field,
                                     ','.join([rc.__name__ for rc in ref_classes])))

lodel/plugin/__init__.py

@@ -1,43 +1,96 @@
 #-*- coding: utf-8 -*-
 
-## @page howto_writeplugin Write a plugin howto
-#
-# @section howto_writeplugin_basicstruct Plugin basic structure
-# A plugins is a python package that have to contains 3 files :
-#- <code>__init__.py</code>
-#- <code>main.py</code> ( defined in @ref lodel.plugin.plugins.MAIN_FILENAME )
-#- <code>confspec.py</code> ( defined in
-#@ref lodel.plugin.plugins.CONFSPEC_FILENAME )
-#
-# There is an example plugin in @ref plugins/dummy
-#
-# @subsection howto_writreplugin_confspec Plugin configuration specification
-# First of all a good practice is to preffix all plugin specific configuration
-# key with <code>lodel2.plugin.PLUGIN_NAME</code>.
-#
-# A configuration specification is a dict containing dict containing
-# tupe(DEFAULT_VALUE, VALIDATOR). The first level dict keys are sections, and
-# the dictionnary contained in it contains conf keys. More information on 
-# validators : @ref lodel.settings.validator
-# 
-# @subsubsection howto_writreplugin_confspec_example Example :
-#
-#A confspec that matches this peace of configuration file
-#<pre>
-#[lodel2.plugin.fooplugin]
-#hello = ...
-#foo = ...
-#bar = ...
-#</pre>
-#would be
-#<pre>
-#{
-#   'lodel2.plugin.fooplugin': {
-#                                   'foo': ...,
-#                                   'bar': ...,
-#                                   'hello': ..., } }
-#</pre>
-# 
+##@defgroup lodel2_plugins Plugins
+#
+#Groups all stuff that concerns plugins
+
+## @page plugin_doc Lodel2 plugin documentation
+#@ingroup lodel2_plugins
+# @section plugin_doc_type Plugin types
+#
+# Plugins are organized into types. A type specify a behavior. For the moment
+# Lodel2 has 4 plugin types :
+# - **datasource** : A datasource connector plugin expose CRUD operation on a
+#particular datasource
+# - **ui** : A user interface plugin provide an interface to lodel2. For the
+#moment two ui are implemented
+#  - interactive python : the default interface, provides access to LeApi 
+#through interactive python interpreter
+#  - webui : a plugin providing a web interface to lodel2
+# - **session_handler** : A session handler plugin expose functions that handles
+#user sessions.
+# - **extensions** : An extension plugin can define 2 kinds of objects :
+#  - hooks using @ref lodel.plugin.hooks.LodelHook decorator
+#  - custom LeApi obect methods using @ref lodel.plugin.plugins.CustomMethod 
+#decorator
+#
+# @subsection Lodel2 scripts
+#
+# In instances an utility is provided : @ref install.lodel_admin . This 
+# utility can be runned as a CLI script 
+#<code>usage: lodel_admin.py [-h] [-L] [ACTION] [OPTIONS [OPTIONS ...]]</code>
+#
+# Each actions is a "lodel2 script". Thoses scripts are parts of plugins.
+# @ref lodel2_script "More informations on lodel2 scripting utilities"
+#
+# @section plugin_doc_struct Common plugin structure
+#
+# All plugin types has to provide mandatories information in order to be 
+# loaded :
+#
+# - A plugin name
+# - A plugin version
+# - A confspec indicating where to find the wanted plugin list (for example 
+#datasources plugins list are indicated in lodel2.datasource_connectors 
+#configuration key see @ref datasource_plugin.DatasourcePlugin::_plist_confspecs ). In
+#fact settings MUST begin by loading wanted plugin list in order to build
+#a "full" confspec
+# - A confspec indicating the plugins allowed settings (will be merged with
+#lodel2 confspecs)
+# - A loader module filename. This module is imported once settings are
+#fully bootstraped and loader. It triggers the module "startup".
+#
+# In order to provide this informations the develloper can use the plugin's
+#package <code>__init__.py</code> file. Some informations are stored in 
+#variables in this file. Available variables are documented in 
+#@ref plugin_init_specs . Here a list of basics variables :
+# - the plugin's name @ref plugins.PLUGIN_NAME_VARNAME
+# - the plugin's version @ref plugins.PLUGIN_VERSION_VARNAME
+# - the plugin's loader filename @ref plugins.LOADER_FILENAME_VARNAME
+# - the plugin's confspec filename @ref plugins.CONFSPEC_FILENAME_VARNAME (
+#set this variable only if you want your confspecs to be in a separated file,
+#else you can put the confspecs directly in a CONFSPEC variable in the
+#<code>__init__.py</code> file see @ref plugins.CONFSPEC_VARNAME )
+# - the plugin's type @ref plugins.PLUGIN_TYPE_VARNAME (if not set use 
+# @ref plugins.DEFAULT_PLUGIN_TYPE )
+# - the plugin's dependencies list @ref plugins.PLUGIN_DEPS_VARNAME
+#
+# This was the variable specification of the <code>__init__.py</code> file.
+#plugins can provide (in the same file) an _activate function ( 
+#<code>def _activate(): returns bool</code>) that return True if the plugin
+#is activable else False
+#
+#An example dummy plugin exists in @ref plugins.dummy
+#
+#@section plugin_doc_childclasses Plugin types implementation
+#
+# Concretely a plugin type is a child class of @ref plugins.Plugin . Plugin 
+# type registration is done automatically using a metaclass for 
+# @ref plugins.Plugin : @ref plugins.MetaPlugType . Doing this way
+# plugin's type list is automatically generated.
+#@note Plugin type handling is not fully automatic because child classes files
+#are not automaticaaly imported. We have to add an import instruction into 
+#@ref plugin file in order to trigger the registration
+#
+#The Plugin child class must set the _plist_confspecs class attribute.
+#
+#More informations :
+# - @ref lodel.plugin.datasource_plugin.DatasourcePlugin "DatasourcePlugin"
+#  - @ref lodel2_datasources "datasources"
+# - @ref lodel.plugin.extensions.Extension "Extensions"
+# - @ref lodel.plugin.interface.InterfacePlugin "InterfacePlugin"
+# - @ref lodel.plugin.sessionhandler.SessionHandlerPlugin "SessionHandlerPlugin"
+#
 
 from .hooks import LodelHook
 from .plugins import Plugin, CustomMethod

lodel/plugin/core_hooks.py

@@ -6,6 +6,7 @@ from lodel import logger
 
 ##@package lodel.plugin.core_hooks
 #@brief Lodel2 internal hooks declaration
+#@ingroup lodel2_plugins
 
 ##@brief Bootstrap hook to check datasources configuration
 @LodelHook('lodel2_bootstraped')

lodel/plugin/core_scripts.py

@@ -1,8 +1,16 @@
 import lodel.plugin.scripts as lodel_script
 
+##@package lodel.plugin.core_scripts
+#@brief Lodel2 internal scripts declaration
+#@ingroup lodel2_plugins
+#@ingroup lodel2_script
+
+
 ##@brief Implements lodel_admin.py discover-plugin action
+#@ingroup lodel2_plugins
+#@ingroup lodel2_script
 #
-#In depth directory scan to find plugins.
+#In depth directory scan to find plugins in order to build a plugin list.
 class DiscoverPlugin(lodel_script.LodelScript):
     _action = 'discover-plugin'
     _description = 'Walk through given folders looking for plugins'

lodel/plugin/datasource_plugin.py

@@ -6,9 +6,14 @@ from lodel.settings.validator import SettingValidator
 #
 #A datasource provide data access to LeAPI typically a connector on a DB
 #or an API
+#
+#Provide methods to initialize datasource attribute in LeAPI LeObject child
+#classes (see @ref leapi.leobject.LeObject._init_datasources() )
+#
 #@note For the moment implementation is done with a retro-compatibilities
 #priority and not with a convenience priority.
 #@todo Refactor and rewrite lodel2 datasource handling
+#@todo Write abstract classes for Datasource and MigrationHandler !!!
 class DatasourcePlugin(Plugin):
     
     ##@brief Stores confspecs indicating where DatasourcePlugin list is stored
@@ -18,16 +23,23 @@ class DatasourcePlugin(Plugin):
         'default': None,
         'validator': SettingValidator('strip', none_is_valid = False) }
     _type_conf_name = 'datasource'
-    
+ 
+    ##@brief Construct a DatasourcePlugin 
+    #@param name str : plugin name
+    #@see plugins.Plugin
     def __init__(self, name):
         super().__init__(name)
         self.__datasource_cls = None
-
+    
+    ##@brief Accessor to the datasource class
+    #@return A python datasource class
     def datasource_cls(self):
         if self.__datasource_cls is None:
             self.__datasource_cls = self.loader_module().Datasource
         return self.__datasource_cls
-
+    
+    ##@brief Accessor to migration handler class
+    #@return A python migration handler class
     def migration_handler_cls(self):
         return self.loader_module().migration_handler_class()
 
@@ -139,8 +151,87 @@ but %s is a %s" % (ds_name, pinstance.__class__.__name__))
     @classmethod
     def get_datasource(cls, ds_plugin_name):
         return cls.get(ds_plugin_name).datasource_cls()
-
+    
+    ##@brief Given a plugin name returns a migration handler class
+    #@param ds_plugin_name str : a datasource plugin name
     @classmethod
     def get_migration_handler(cls, ds_plugin_name):
         return cls.get(ds_plugin_name).migration_handler_cls()
- 
+
+##@page lodel2_datasources Lodel2 datasources
+#
+#@par lodel2_datasources_intro Intro
+# A single lodel2 website can interact with multiple datasources. This page
+# aims to describe configuration & organisation of datasources in lodel2.
+# Each object is attached to a datasource. This association is done in the
+# editorial model, the datasource is identified by a name.
+#
+#@par Datasources declaration
+# To define a datasource you have to write something like this in confs file :
+#<pre>
+#[lodel2.datasources.DATASOURCE_NAME]
+#identifier = DATASOURCE_FAMILY.SOURCE_NAME
+#</pre>
+# See below for DATASOURCE_FAMILY & SOURCE_NAME
+#
+#@par Datasources plugins
+# Each datasource family is a plugin ( 
+#@ref plugin_doc "More informations on plugins" ). For example mysql or a 
+#mongodb plugins. Here is the CONFSPEC variable templates for datasources 
+#plugin
+#<pre>
+#CONFSPEC = {
+#                'lodel2.datasource.example.*' : {
+#                    'conf1' : VALIDATOR_OPTS,
+#                    'conf2' : VALIDATOR_OPTS,
+#                    ...
+#                }
+#}
+#</pre>
+#MySQL example
+#<pre>
+#CONFSPEC = {
+#                'lodel2.datasource.mysql.*' : {
+#                    'host': (   'localhost',
+#                                SettingValidator('host')),
+#                    'db_name': (    'lodel',
+#                                    SettingValidator('string')),
+#                    'username': (   None,
+#                                    SettingValidator('string')),
+#                    'password': (   None,
+#                                    SettingValidator('string')),
+#                }
+#}
+#</pre>
+#
+#@par Configuration example
+#<pre>
+# [lodel2.datasources.main]
+# identifier = mysql.Core
+# [lodel2.datasources.revues_write]
+# identifier = mysql.Revues
+# [lodel2.datasources.revues_read]
+# identifier = mysql.Revues
+# [lodel2.datasources.annuaire_persons]
+# identifier = persons_web_api.example
+# ;
+# ; Then, in the editorial model you are able to use "main", "revues_write", 
+# ; etc as datasource
+# ;
+# ; Here comes the datasources declarations
+# [lodel2.datasource.mysql.Core]
+# host = db.core.labocleo.org
+# db_name = core
+# username = foo
+# password = bar
+# ;
+# [lodel2.datasource.mysql.Revues]
+# host = revues.org
+# db_name = RO
+# username = foo
+# password = bar
+# ;
+# [lodel2.datasource.persons_web_api.example]
+# host = foo.bar
+# username = cleo
+#</pre>

lodel/plugin/hooks.py

@@ -27,6 +27,7 @@ class DecoratedWrapper(object):
             self._hook.__name__, self._priority)
 
 ##@brief Decorator designed to register hook's callbacks
+#@ingroup lodel2_plugins
 #
 # @note Decorated functions are expected to take 3 arguments :
 #  - hook_name : the called hook name

lodel/plugin/plugins.py

@@ -14,6 +14,7 @@ from .exceptions import *
 from lodel.exceptions import *
 
 ## @package lodel.plugins Lodel2 plugins management
+#@ingroup lodel2_plugins
 #
 # Lodel2 plugins are stored in directories
 # A typicall lodel2 plugin directory structure looks like :
@@ -21,31 +22,54 @@ from lodel.exceptions import *
 # - main.py containing hooks registration etc
 # - confspec.py containing a configuration specification dictionary named CONFSPEC
 
+##@defgroup plugin_init_specs Plugins __init__.py specifications
+#@ingroup lodel2_plugins
+#@{
+
 ##@brief The package in which we will load plugins modules
 VIRTUAL_PACKAGE_NAME = 'lodel.plugins'
 ##@brief The temporary package to import python sources
 VIRTUAL_TEMP_PACKAGE_NAME = 'lodel.plugin_tmp'
 ##@brief Plugin init filename
 INIT_FILENAME = '__init__.py' # Loaded with settings
+##@brief Name of the variable containing the plugin name
 PLUGIN_NAME_VARNAME = '__plugin_name__'
+##@brief Name of the variable containing the plugin type
 PLUGIN_TYPE_VARNAME = '__plugin_type__'
+##@brief Name of the variable containing the plugin version
 PLUGIN_VERSION_VARNAME = '__version__'
+##@brief Name of the variable containing the confpsec filename
 CONFSPEC_FILENAME_VARNAME = '__confspec__'
+##@brief Name of the variable containing the confspecs
 CONFSPEC_VARNAME = 'CONFSPEC'
+##@brief Name of the variable containing the loader filename
 LOADER_FILENAME_VARNAME = '__loader__'
+##@brief Name of the variable containing the plugin dependencies
 PLUGIN_DEPS_VARNAME = '__plugin_deps__'
+##@brief Name of the optionnal activate method
 ACTIVATE_METHOD_NAME = '_activate'
 ##@brief Discover stage cache filename
 DISCOVER_CACHE_FILENAME = '.plugin_discover_cache.json'
 ##@brief Default & failover value for plugins path list
 DEFAULT_PLUGINS_PATH_LIST = ['./plugins']
 
+##@brief List storing the mandatory variables expected in a plugin __init__.py
+#file
 MANDATORY_VARNAMES = [PLUGIN_NAME_VARNAME, LOADER_FILENAME_VARNAME, 
     PLUGIN_VERSION_VARNAME]
 
+##@brief Default plugin type
 DEFAULT_PLUGIN_TYPE = 'extension' #Value found in lodel/plugin/extensions.py::Extensions._type_conf_name
 
+## @}
+
 ##@brief Describe and handle version numbers
+#@ingroup lodel2_plugins
+#
+#A version number can be represented by a string like MAJOR.MINOR.PATCH
+#or by a list [MAJOR, MINOR,PATCH ].
+#
+#The class implements basics comparison function and string repr
 class PluginVersion(object):
 
     PROPERTY_LIST = ['major', 'minor', 'revision' ]
@@ -82,14 +106,17 @@ but %d arguments found" % len(args))
             for i,v in enumerate(args):
                 self.__version[i] = v
     
+    ##@brief Property to access major version number
     @property
     def major(self):
         return self.__version[0]
 
+    ##@brief Property to access minor version number
     @property
     def minor(self):
         return self.__version[1]
 
+    ##@brief Property to access patch version number
     @property
     def revision(self):
         return self.__version[2]
@@ -147,8 +174,8 @@ to generic PluginVersion comparison function : '%s'" % cmp_fun_name)
         return {'major': self.major, 'minor': self.minor,
             'revision': self.revision}
 
-##@brief Plugin metaclass that allows to "catch" child class
-#declaration
+##@brief Plugin metaclass that allows to "catch" child class declaration
+#@ingroup lodel2_plugins
 #
 #Automatic script registration on child class declaration
 class MetaPlugType(type):
@@ -158,6 +185,7 @@ class MetaPlugType(type):
     #key is the _type_conf_name and value is the class
     _all_ptypes = dict()
 
+    ##@brief type constructor reimplementation
     def __init__(self, name, bases, attrs):
         #Here we can store all child classes of Plugin
         super().__init__(name, bases, attrs)
@@ -165,15 +193,24 @@ class MetaPlugType(type):
             return
         #Regitering a new plugin type
         MetaPlugType._all_ptypes[self._type_conf_name] = self
-
+    
+    ##@brief Accessor to the list of plugin types
+    #@return A copy of _all_ptypes attribute (a dict with typename as key
+    #and the class as value)
     @classmethod
     def all_types(cls):
         return copy.copy(cls._all_ptypes)
-
+    
+    ##@brief Accessor to the list of plugin names
+    #@return a list of plugin name
     @classmethod
     def all_ptype_names(cls):
         return list(cls._all_ptypes.keys())
-
+    
+    ##@brief Given a plugin type name return a Plugin child class
+    #@param ptype_name str : a plugin type name
+    #@return A Plugin child class
+    #@throw PluginError if ptype_name is not an exsiting plugin type name
     @classmethod
     def type_from_name(cls, ptype_name):
         if ptype_name not in cls._all_ptypes:
@@ -181,6 +218,7 @@ class MetaPlugType(type):
         return cls._all_ptypes[ptype_name]
 
 ##@brief Handle plugins
+#@ingroup lodel2_plugins
 #
 # An instance represent a loaded plugin. Class methods allow to load/preload
 # plugins.
@@ -225,14 +263,18 @@ class Plugin(object, metaclass=MetaPlugType):
     # @throw PluginError
     def __init__(self, plugin_name):
         
+        ##@brief The plugin name
         self.name = plugin_name
+        ##@brief The plugin package path
         self.path = self.plugin_path(plugin_name)
         
         ##@brief Stores the plugin module
         self.module = None
-        ##@breif Stores the plugin loader module
+        ##@brief Stores the plugin loader module
         self.__loader_module = None
+        ##@brief The plugin confspecs
         self.__confspecs = dict()
+        ##@brief Boolean flag telling if the plugin is loaded or not
         self.loaded = False
         
         # Importing __init__.py infos in it
@@ -295,7 +337,6 @@ class Plugin(object, metaclass=MetaPlugType):
             self.__type = DEFAULT_PLUGIN_TYPE
         self.__type = str(self.__type).lower()
         if self.__type not in MetaPlugType.all_ptype_names():
-            print("FUCK : ", MetaPlugType.all_ptype_names())
             raise PluginError("Unknown plugin type '%s'" % self.__type)
         # Load plugin name from init file (just for checking)
         try:
@@ -474,6 +515,9 @@ name differ from the one found in plugin's init file"
     def confspecs(self):
         return copy.copy(self.__confspecs)
 
+    ##@brief Accessor to confspec indicating where we can find the plugin list
+    #@note Abtract method implemented only for Plugin child classes
+    #This attribute indicate where we fetch the plugin list.
     @classmethod
     def plist_confspecs(cls):
         if cls._plist_confspecs is None:
@@ -546,7 +590,6 @@ file : '%s'. Running discover again..." % DISCOVER_CACHE_FILENAME)
         if ptype not in MetaPlugType.all_ptype_names():
             raise PluginError("Unknown plugin type '%s'" % ptype)
         pcls = MetaPlugType.type_from_name(ptype)
-        print("\n\n\nINSTANCIATING : ", pcls, " from name : ", ptype)
         plugin = pcls(plugin_name)
         cls._plugin_instances[plugin_name] = plugin
         logger.debug("Plugin %s available." % plugin)
@@ -582,7 +625,14 @@ file : '%s'. Running discover again..." % DISCOVER_CACHE_FILENAME)
             pass
 
         return plist[plugin_name]['path']
-        
+    
+    ##@brief Return the plugin module name
+    #
+    #This module name is the "virtual" module where we imported the plugin.
+    #
+    #Typically composed like VIRTUAL_PACKAGE_NAME.PLUGIN_NAME
+    #@param plugin_name str : a plugin name
+    #@return a string representing a module name
     @classmethod
     def plugin_module_name(cls, plugin_name):
         return "%s.%s" % (VIRTUAL_PACKAGE_NAME, plugin_name)
@@ -596,7 +646,8 @@ file : '%s'. Running discover again..." % DISCOVER_CACHE_FILENAME)
     def start(cls, plugins):
         for plugin_name in plugins:
             cls.register(plugin_name)
-        
+    
+    ##@brief Attempt to "restart" the Plugin class
     @classmethod
     def clear(cls):
         if cls._plugin_directories is not None:
@@ -778,6 +829,7 @@ file : '%s'. Running discover again..." % DISCOVER_CACHE_FILENAME)
 
 ##@brief Decorator class designed to allow plugins to add custom methods
 #to LeObject childs (dyncode objects)
+#@ingroup lodel2_plugins
 #
 class CustomMethod(object):
     ##@brief Stores registered custom methods

lodel/plugin/scripts.py

@@ -4,11 +4,22 @@ import sys
 from lodel import logger
 from lodel.exceptions import *
 
+##@defgroup lodel2_script Administration scripts
+#@ingroup lodel2_plugins
+
+##@package lodel.plugin.script
+#@brief Lodel2 utility for writting administration scripts
+#@ingroup lodel2_plugins
+#@ingroup lodel2_script
+
 ##@brief Stores registered scripts
+#@todo store it in MetaLodelScript
 __registered_scripts = dict()
 
 ##@brief LodelScript metaclass that allows to "catch" child class
 #declaration
+#@ingroup lodel2_script
+#@ingroup lodel2_plugins
 #
 #Automatic script registration on child class declaration
 class MetaLodelScript(type):
@@ -48,6 +59,10 @@ action identifier" % name)
     def __str__(self):
         return '%s : %s' % (self._action, self._description)
 
+
+##@brief Class designed to facilitate custom script writting
+#@ingroup lodel2_plugins
+#@ingroup lodel2_script
 class LodelScript(object, metaclass=MetaLodelScript):
     
     ##@brief A string to identify the action
@@ -146,7 +161,6 @@ def main_run():
     action = sys.argv[1].lower()
     if action not in __registered_scripts:
         #Trying to parse argument with default parser
-        print("PASSAGE")
         args = default_parser.parse_args()
         if args.list_actions:
             print("Available actions :")

lodel/plugin/sessionhandler.py

@@ -5,6 +5,7 @@ from lodel.settings.validator import SettingValidator
 ##@brief SessionHandlerPlugin metaclass designed to implements a wrapper
 #between SessionHandlerPlugin classmethod and plugin loader functions
 class SessionPluginWrapper(MetaPlugType):
+
     ##@brief Constant that stores all possible session actions
     #
     #Key is the SessionHandlerPlugin method name and value is SessionHandler
@@ -32,15 +33,10 @@ functions, but no session handler initialized")
         return super().__getattribute__(name)
 
 
-##@page lodel2_plugins Lodel2 plugins system
-#
-# @par Plugin structure
-#A plugin is  a package (a folder containing, at least, an __init__.py file.
-#This file should expose multiple things :
-# - a CONFSPEC variable containing configuration specifications
-# - an _activate() method that returns True if the plugin can be activated (
-# optionnal)
+##@brief Singleton class designed to handle session handler plugin
 #
+#@note This class is a singleton because only one session handler can be
+#loaded by instance
 class SessionHandlerPlugin(Plugin, metaclass=SessionPluginWrapper): 
     ##@brief Stores the singleton instance
     _instance = None

plugins/dummy_datasource/__init__.py

@@ -13,78 +13,4 @@ CONFSPEC = {
                     SettingValidator('dummy'))}
 }
 
-##@page lodel2_datasources Lodel2 datasources
-#
-#@par lodel2_datasources_intro Intro
-# A single lodel2 website can interact with multiple datasources. This page
-# aims to describe configuration & organisation of datasources in lodel2.
-# Each object is attached to a datasource. This association is done in the
-# editorial model, the datasource is identified by a name.
-#
-#@par Datasources declaration
-# To define a datasource you have to write something like this in confs file :
-#<pre>
-#[lodel2.datasources.DATASOURCE_NAME]
-#identifier = DATASOURCE_FAMILY.SOURCE_NAME
-#</pre>
-# See below for DATASOURCE_FAMILY & SOURCE_NAME
-#
-#@par Datasources plugins
-# Each datasource family is a plugin. For example mysql or a mongodb plugins.
-# Here is the CONFSPEC variable templates for datasources plugins
-#<pre>
-#CONFSPEC = {
-#                'lodel2.datasource.example.*' : {
-#                    'conf1' : VALIDATOR_OPTS,
-#                    'conf2' : VALIDATOR_OPTS,
-#                    ...
-#                }
-#}
-#</pre>
-#MySQL example
-#<pre>
-#CONFSPEC = {
-#                'lodel2.datasource.mysql.*' : {
-#                    'host': (   'localhost',
-#                                SettingValidator('host')),
-#                    'db_name': (    'lodel',
-#                                    SettingValidator('string')),
-#                    'username': (   None,
-#                                    SettingValidator('string')),
-#                    'password': (   None,
-#                                    SettingValidator('string')),
-#                }
-#}
-#</pre>
-#
-#@par Configuration example
-#<pre>
-# [lodel2.datasources.main]
-# identifier = mysql.Core
-# [lodel2.datasources.revues_write]
-# identifier = mysql.Revues
-# [lodel2.datasources.revues_read]
-# identifier = mysql.Revues
-# [lodel2.datasources.annuaire_persons]
-# identifier = persons_web_api.example
-# ;
-# ; Then, in the editorial model you are able to use "main", "revues_write", 
-# ; etc as datasource
-# ;
-# ; Here comes the datasources declarations
-# [lodel2.datasource.mysql.Core]
-# host = db.core.labocleo.org
-# db_name = core
-# username = foo
-# password = bar
-# ;
-# [lodel2.datasource.mysql.Revues]
-# host = revues.org
-# db_name = RO
-# username = foo
-# password = bar
-# ;
-# [lodel2.datasource.persons_web_api.example]
-# host = foo.bar
-# username = cleo
-#</pre>
+