Updated the doxygen documentation

Adding images support for doxygen documentation ( in doc/img ) + automated images generation with graphviz & make

.gitignore

@@ -3,5 +3,6 @@
 .git
 .idea
 settings_local.py
-doc
+doc/html
+doc/*.sqlite3.db
 .*.swp

Doxyfile

@@ -703,7 +703,7 @@ CITE_BIB_FILES         =
 # messages are off.
 # The default value is: NO.
 
-QUIET                  = NO
+QUIET                  = YES
 
 # The WARNINGS tag can be used to turn on/off the warning messages that are
 # generated to standard error ( stderr) by doxygen. If WARNINGS is set to YES
@@ -892,7 +892,7 @@ EXAMPLE_RECURSIVE      = NO
 # that contain images that are to be included in the documentation (see the
 # \image command).
 
-IMAGE_PATH             = 
+IMAGE_PATH             = doc/img
 
 # The INPUT_FILTER tag can be used to specify a program that doxygen should
 # invoke to filter for each input file. Doxygen will invoke the filter program

Lodel/__init__.py

@@ -8,6 +8,7 @@
 #
 # @section mainpage_docs Documentation
 #
+# - Lodel2 architecture : @subpage lodel2_arch 
 # - Fieldtypes : @subpage lodel2_fieldtypes
 # @subsection mainpage_docs_leapi LeAPI
 #
@@ -27,4 +28,49 @@
 # - @ref leapi
 # - DataSource
 #  - DataSource.MySQL
+#
+
+## @page lodel2_arch Lodel2 architecture
+#
+#
+# @section lodel2_arch_basic Lodel2
+#
+# Lodel 2 is a CMS that allows to define content types ......
+#
+# @section lodel2_arch_edmod Lodel2 Editorial Model
+#
+# The editorial model is the part of lodel2 that allows to defines content types.
+#
+# To handle this the editorial model has 3  abstractions :
+# - Classes
+# - Types
+# - Fields
+#
+# @warning An editorial model does NOT contains values.
+#
+# The editorial model is used to generate the dynamic part of the Lodel2 API ( see @ref leapi )
+#
+# @subsection lodel2_arch_edmod_classes Editorial model classes ( EmClass )
+#
+# An EmClass is basically a named collection of EmFields ( see @ref lodel2_arch_edmod_fields ) associated with a classtype.
+#
+# Classtypes are "family" of EmClasses. They defines allowed hierarchical relations between EmClass.
 # 
+# @subsection lodel2_arch_edmod_types Editorial model types ( EmType )
+#
+# An EmType is a named EmClass specialization. In fact some EmField in an EmClass can be defined as optionnal and then be selected
+# or not to be included in an EmType.
+# 
+# @subsection lodel2_arch_edmod_fields Editorial model fields ( EmField )
+#
+# EmFields defines what kind of datas can be stored in EmTypes. Actually its the associationg with an EmFieldtype ( see @ref lodel2_fieldtypes )
+# that really defines what kind of datas can be stored.
+#
+# @subsection lodel2_arch_edmod_fig Editorial model figures
+#
+# @subsubsection lodel2_arch_edmod_fig_components Editorial model main components
+# @image html graphviz/em_components.png
+# @subsubsection lodel2_arch_edmod_fig_relations Editorial model relations between components
+# @image html graphviz/em_relations.png
+# @subsubsection lodel2_arch_edmod_fig_hierarchy Hierarchical relations between EmTypes given a classtype
+# @image html graphviz/em_types_hierarch.png

Makefile

@@ -1,21 +1,42 @@
 all: check doc pip
 
+# Running unit tests
 check:
 	python -m unittest -v
 
-doc: cleandoc
-	doxygen
-
+# Rule to update libs
 pip: cleanpycache
 	pip install --upgrade -r requirements.txt
 
+#
+# Documentation rules
+#
+graphviz_images_path = doc/img/graphviz
+
+doc: cleandoc docimages
+	doxygen
+
+# Generating graphviz images
+docimages:
+	cd $(graphviz_images_path); make
+
+#
+# Cleaning rules
+#
 .PHONY: check doc clean cleanpyc cleandoc cleanpycache
 
-cleandoc:
-	-rm -Rfv ./doc/
+clean: cleanpyc cleandoc cleanpycache
+
+# Documentation cleaning
+cleandoc: cleandocimages
+	-rm -Rfv ./doc/html ./doc/doxygen_sqlite3.db
+
+cleandocimages:
+	cd $(graphviz_images_path); make clean
+
+# Python cleaning
 cleanpyc:
 	-find ./ |grep -E "\.pyc$$" |xargs rm -fv 2>/dev/null
 cleanpycache: cleanpyc
 	-find ./ -type d |grep '__pycache__' | xargs rmdir -fv 2>/dev/null
 
-clean: cleanpyc cleandoc cleanpycache

doc/img/graphviz/Makefile

@@ -0,0 +1,14 @@
+dotfiles := $(wildcard *.dot)
+images := $(patsubst %.dot,%.png,$(wildcard *.dot))
+
+all: $(images)
+	
+%.png: %.dot
+	dot -Tpng $< > $@
+
+.PHONY: clean distclean
+
+clean:
+	-rm $(images)
+
+distclean: clean

doc/img/graphviz/em_components.dot

@@ -0,0 +1,13 @@
+digraph editorial_model_components {
+
+	label="Editorial model components"
+
+	classtypes [ label="{ entity | person | index }", shape=record]
+	class [ label="<f0> Class| { <f2> fields|<f3> optionnal field }", shape=record ]
+	type [ label="<f0> Type| { <f2> fields| <f3> selected field }", shape=record ]
+
+	classtypes -> class [ label="Defines possibles hierarchy" ]
+	class:f0 -> type:f0 [ label="specialize", style="dotted" ]
+	class:f2 -> type:f2 [ label="inherit"]
+	class:f3 -> type:f3 [ label="select" ]
+}

doc/img/graphviz/em_relations.dot

@@ -0,0 +1,26 @@
+digraph editorial_model_relations {
+	
+	label="Editorial Model relations"
+
+	classtypes
+
+	r_class1 [ label="<f0> Class 1| {STR |INTEGER(optionnal) | STR | REL_TO_TYPE}", shape=record ]
+
+	r_class2 [ label="<f0> Class 2| {STR |STR }", shape=record ]
+
+	r_type1 [ label="<f0> Type 1| { STR |INTEGER | STR |<fr>REL_TO_TYPE}}", shape=record ]
+	r_type2 [ label="<f0> Type 2|{ STR | STR |<fr>REL_TO_TYPE}", shape=record ]
+
+	r_type3 [ label="<f0> Type 3|{ STR |STR }", shape=record ]
+
+	classtypes -> r_class1
+	classtypes -> r_class2
+
+	r_class1 -> r_type1 [ label="inherit", style="dotted" ]
+	r_class1 -> r_type2 [ label="inherit", style="dotted" ]
+
+	r_class2 -> r_type3 [ label="inherit", style="dotted" ]
+
+	r_type1:fr -> r_class2 [ label="link to Class 2" ]
+	r_type2:fr -> r_class1 [ label="link to Class 1" ]
+}

doc/img/graphviz/em_types_hierarch.dot

@@ -0,0 +1,77 @@
+digraph em_types_hierarchy {
+
+	label="Editorial Model types hierarchy"
+
+	subgraph cluster_person {
+		label="Person"
+		h_person [ label="Person", shape="tripleoctagon" ]
+
+		hc3 [ label="Class 3", shape="doubleoctagon"]
+		hc4 [ label="Class 4", shape="doubleoctagon"]
+
+		ht6 [ label="Type 6", shape="octagon" ]
+		ht7 [ label="Type 7", shape="octagon" ]
+		ht8 [ label="Type 8", shape="octagon" ]
+
+		h_person -> {hc3, hc4}
+
+		hc3 -> { ht6,ht7 }
+		hc4 -> ht8
+
+		ht6 -> ht7 [ label="identity", color="blue" ]
+		ht6 -> ht8 [ label="identity", color="blue" ]
+		ht8 -> ht8 [ label="identity", color="blue" ]
+	}
+
+	subgraph cluster_entity {
+		label="Entity"
+		h_entity [ label="Entity", shape="tripleoctagon" ]
+
+		hc1 [ label="Class 1", shape="doubleoctagon"]
+		hc2 [ label="Class 2", shape="doubleoctagon"]
+
+		ht1 [ label="Type 1", shape="octagon" ]
+		ht2 [ label="Type 2", shape="octagon" ]
+		ht3 [ label="Type 3", shape="octagon" ]
+		ht4 [ label="Type 4", shape="octagon" ]
+		ht5 [ label="Type 5", shape="octagon" ]
+
+		
+		h_entity -> { hc1, hc2 }
+
+		hc1 -> { ht1,ht2,ht3 }
+		hc2 -> { ht4, ht5 }
+
+		ht1 -> ht1 [label="translation", color="red"]
+		ht3 -> ht3 [label="translation", color="red"]
+		ht5 -> ht5 [label="translation", color="red"]
+		ht4 -> ht1 [ label="parent", color="green"]
+		ht2 -> ht1 [ label="parent", color="green"]
+		ht5 -> ht4 [ label="parent", color="green"]
+		ht3 -> ht4 [ label="parent", color="green"]
+		ht3 -> ht1 [ label="parent", color="green"]
+
+
+	}
+
+	subgraph cluster_entry {
+		label="Entry"
+		h_entry [ label="Entry", shape="tripleoctagon" ]
+
+		hc5 [ label="Class 5", shape="doubleoctagon"]
+
+		ht9 [ label="Type 9", shape="octagon" ]
+		ht10 [ label="Type 10", shape="octagon" ]
+
+		h_entry -> hc5
+
+		hc5 -> {ht9, ht10}
+
+		ht9 -> ht9 [ label="parent", color="green" ]
+		ht9 -> ht9 [ label="translation", color="red" ]
+		ht10 -> ht10 [ label="translation", color="red" ]
+	}
+
+	ht5 -> hc3 [ label="relation to type", style="dotted"]
+	ht2 -> hc5 [ label="relation to type", style="dotted"]
+}

doc/img/graphviz/lodel2_archi.dot

@@ -0,0 +1,14 @@
+digraph Lodel2_architecture {
+	
+
+	ui [ label="User interface" ]
+	leapi [ label="<api>Lodel Editorial API|{Static API|<dynamic> Dynamically generated API}", shape=record ]
+	editorial_model [ label="<em>Editorial Model|{Classes|Types|{<fields>Fields|<ftype>fieldtypes}}", shape=record ]
+
+	editorial_model:em -> leapi:dynamic [ label="Generate" ]
+	editorial_model:ftype -> editorial_model:fields [ label="Defines field value" ]
+	leapi -> editorial_model:ftype [ label="Asks for data validation" ]
+	ui -> leapi:api
+	leapi:api -> ui
+
+}