[doc] Rewamping the documentation structure.

TODO: Homogeneous relationship between debugging information.
Giving more python examples.

doc/Doxyfile.extra.in

@@ -4,3 +4,6 @@ IMAGE_PATH             = @CMAKE_SOURCE_DIR@/doc/pictures \
                          @CMAKE_SOURCE_DIR@/doc/figures
 
 FILE_PATTERNS          = *.cc *.cpp *.h *.hh *.hxx
+
+TAGFILES	       = \
+"@CMAKE_INSTALL_PREFIX@/share/doc/dynamic-graph-python.doxytag = @CMAKE_INSTALL_PREFIX@/share/doc/dynamic-graph-python"
\ No newline at end of file

doc/additionalDoc/debug.h

+/**
+\page debug Debugging
+
+They are several ways to perform debugging in dynamic-graph.
+You can do it:
+- with entities inside the graph:\subpage tracerdoc
+- programmatically inside the entity in C++ using member of the entities:
+\subpage tracerrealtimedoc
+- programmatically in C++ with macros
+**/

doc/additionalDoc/entity.h

+/**
+\page subpage_entities Entities
+
+\section section_entities Entities
+\subsection entity_definition General definition
+\image html entity.png
+
+Despite the fact that it looks very similar to a ROS node or a CORBA/OpenRTM server, an entity is simply a C++ object.
+The main idea is that this entity is providing mostly a data-driven functionnality working at very high rate (\f$ 200 Hz\f$ or \f$ 1 kHz \f$)
+and should have a minimal computational time foot-print.
+
+For this signals (or ports to use a more classical terminology) are providing a time dependency between data.
+To implement this, an output signal is linked with a method of the entity. The method calls input signals or use other means
+to get the needed data.
+It might be provided by the connection with remote computers through a middleware, or specific protocols,
+but in general the external data is based upon the sensor values provided by a "Device" entity.
+For this reason the signal evaluations are realized through the cascade of dependencies and start from the evaluation of an input
+signal of a periodic node (in general the device). This is realized inside a \b real-time thread.
+
+To add flexibility to a node, it is possible to add command with arguments to modify the internal behavior of the entity
+or get information from the entity.
+As a command is in general asynchronous and rare with respect to the data-flow scheme for the signals the command is in general
+executed in a \b none-real-time thread.
+
+\subsection entity_classes Entity class
+Entities are implemented as C++ classes and compiled as dynamic libraries. They can be loaded and instancied dynamically.
+It is therefore necessary to specify the location of their dynamical libraries.
+However given the time it might take to load the library, it is not advised to do that during a control-law computation.
+Entity instanciation also implies memory allocation which is also time consuming and thus not advised inside a real-time thread.
+
+The entities will be placed in ${PREFIX}/lib/plugin (since this may change, it is advised to
+check the install log or the CMakeLists.txt file to check the installation path).
+
+\subsection entities List of entities in this package
+Since most of the functionality in projects using the dynamic-graph framework
+is exposed from entities, here is a short description of all the entities contained in
+this package. Note that most entities are contained in a binary file that closely matches
+the entities' names in the scripts; loading this file with the plugin loader will
+enable creation of this entity through the factory.
+\li \ref tracerdoc
+\li \ref tracerrealtimedoc
+
+\subsection specific_semantics Specific semantics with entities
+
+It is possible to derive classes and apply specific semantic for the entities. In our case we are interested in specific control semantics:
+\li Tasks (more information <a href="http://stack-of-tasks.github.io/sot-core/doxygen/HEAD/a00089.html">here</a>)
+\li Features (more information <a href="http://stack-of-tasks.github.io/sot-core/doxygen/HEAD/a00030.html">here</a>)
+\li Solver (more information <a href="http://stack-of-tasks.github.io/sot-core/doxygen/HEAD/a00078.html">here</a>)
+
+*/

doc/additionalDoc/factory.h

+/**
+\page subp_factory Factory
+\section sec_factory Factory
+
+The class \ref dynamicgraph::FactoryStorage is a singleton which register the entity classes and which is allowing the instancation of such classes.
+*/

doc/additionalDoc/graph.h

+/**
+\page page_graph Graph
+
+
+In this package, the graph considered are directed graphs.
+
+In dynamic-graph a graph is build with:
+- computational nodes which are entities \subpage subpage_entities.
+- directed edges which are created by connecting input and output signals \subpage subp_signals.
+- managing the nodes is done through a factory \subpage subp_factory providing classes and a way to create instances from this list of classes.
+- the instances of node are handled through a pool \subpage subp_pool
+
+We strongly recommend to use a scripting language such as Python to 
+manage the graph.
+See <c>dynamic-graph-python</c> for more information on binding dynamic-graph with Python.
+
+It is possible to display the graph of entities \subpage writegraphdoc
+
+
+*/

doc/additionalDoc/package.h

@@ -47,6 +47,8 @@ A scheme of the real-time control graph used for the humanoid robot HRP-2 is dep
 
 \image html Concept-Software-Fig.png
 
+You can find an example of a real example of control graph at \ref writegraphdoc.
+
 <p>The device therefore has a specific input which should contain the control vector.
 This control vector is the result of a computation solving a control problem.
 The entity in charge of solving this control problem is called "Solver" in the previous
@@ -84,73 +86,8 @@ create instances of entities.</p>
 computation of signal values, which is a critical point for real-time systems\n
 See \ref scriptingabout
 
-\section entity Computational Entity
-\image html entity.png
-
-\subsection entity_definition General definition
-Despite the fact that it looks very similar to a ROS node or a CORBA/OpenRTM server, an entity is simply a C++ object.
-The main idea is that this entity is providing mostly a data-driven functionnality working at very high rate (\f$ 200 Hz\f$ or \f$ 1 kHz \f$)
-and should have a minimal computational time foot-print.
-
-For this signals (or ports to use a more classical terminology) are providing a time dependency between data.
-To implement this, an output signal is linked with a method of the entity. The method calls input signals or use other means
-to get the needed data.
-It might be provided by the connection with remote computers through a middleware, or specific protocols,
-but in general the external data is based upon the sensor values provided by a "Device" entity.
-For this reason the signal evaluations are realized through the cascade of dependencies and start from the evaluation of an input
-signal of a periodic node (in general the device). This is realized inside a \b real-time thread.
-
-To add flexibility to a node, it is possible to add command with arguments to modify the internal behavior of the entity
-or get information from the entity.
-As a command is in general asynchronous and rare with respect to the data-flow scheme for the signals the command is in general
-executed in a \b none-real-time thread.
-
-\subsection entity_classes Entity class
-Entities are implemented as C++ classes and compiled as dynamic libraries. They can be loaded and instancied dynamically.
-It is therefore necessary to specify the location of their dynamical libraries.
-However given the time it might take to load the library, it is not advised to do that during a control-law computation.
-Entity instanciation also implies memory allocation which is also time consuming and thus not advised inside a real-time thread.
-
-The entities will be placed in ${PREFIX}/lib/plugin (since this may change, it is advised to
-check the install log or the CMakeLists.txt file to check the installation path).
-
-\subsection entities List of entities in this package
-Since most of the functionality in projects using the dynamic-graph framework
-is exposed from entities, here is a short description of all the entities contained in
-this package. Note that most entities are contained in a binary file that closely matches
-the entities' names in the scripts; loading this file with the plugin loader will
-enable creation of this entity through the factory.
-\li \ref tracerdoc
-\li \ref tracerrealtimedoc
-
-\subsection specific_semantics Specific semantics with entities
-
-It is possible to derive classes and apply specific semantic for the entities. In our case we are interested in specific control semantics:
-\li Tasks (more information <a href="http://stack-of-tasks.github.io/sot-core/doxygen/HEAD/a00089.html">here</a>)
-\li Features (more information <a href="http://stack-of-tasks.github.io/sot-core/doxygen/HEAD/a00030.html">here</a>)
-\li Solver (more information <a href="http://stack-of-tasks.github.io/sot-core/doxygen/HEAD/a00078.html">here</a>)
-
-\section sigintro Signals
-
-Entities can output different types of signals. All signals are templated by a Time
-tick type parameter (which is used in the caching of signals) - usually \c int. Signals
-are also templated after the type of data they accept or provide. For example:
-(example)
-For a more detailed programmer-oriented description of signals, please see \ref signals
-
-\section graph Graph
-
-In this package, the graph considered are directed graphs.
-
-\subsection factory Factory
-
-The class \ref dynamicgraph::FactoryStorage is a singleton which register the entity classes and which is allowing the instancation of such classes.
-
-\subsection pool Pool
-The class \ref dynamicgraph::PoolStorage keeps track of the entities instanciated with the factory.
-The entities are the graph nodes. Signals are constructed during the class instanciation, they do not live independently
-from the entities. Signals are the directed edges of the graph.
-The pool can write a file representing the graph of entities.
+
+
 
 \section usecase How to use this package
 \subsection use_programmtically Programmatically

doc/additionalDoc/pool.h

+/**
+\page subp_pool Pool
+\section pool Pool
+The class \ref dynamicgraph::PoolStorage keeps track of the entities instanciated with the factory.
+The entities are the graph nodes. Signals are constructed during the class instanciation, they do not live independently
+from the entities. Signals are the directed edges of the graph.
+The pool can write a file representing the graph of entities.
+*/

doc/additionalDoc/signal.h

+/**
+\page subp_signals Signals
+\section sec_sigintro Signals
+
+Entities can output different types of signals. All signals are templated by a Time
+tick type parameter (which is used in the caching of signals) - usually \c int. Signals
+are also templated after the type of data they accept or provide. For example:
+(example)
+For a more detailed programmer-oriented description of signals, please see \ref signals
+*/

doc/additionalDoc/tracer-real-timedoc.h

 /**
 \page tracerrealtimedoc TracerRealTime
-\section description Description
+
+\section tracerrealtimedoc_description Description
 The \b TracerRealTime entity monitors a set of signals with real-time constraints; its
 function is very similar to the Tracer, except that all traces are recorded to a
 memory buffer, which can be emptied at any time.
-\section commands Commands
+
+\section tracerrealtimedoc_commands Commands
 The \b commands that this entity exposes are:
 \code
 empty (discards all buffers)
@@ -16,13 +18,12 @@ Plus all the commands exposed by \ref tracerdoc
 For more information on the signals exposed by this entity, please check the
 code documentation of the dynamicgraph::Tracer class.
 
-\section sample Sample usage
+\section tracerrealtimedoc_sample Sample usage
 See \ref tracerdoc for a code sample of using TracerRealTime.
 
-\section addi Additional information
+\section tracerrealtimedoc_addi Additional information
 See doxygen documentation for the class dynamicgraph::TracerRealTime
 
-\section generates Generated plugin file
+\section tracerrealtimedoc_generates Generated plugin file
 tracer-real-time.dll or tracer-real-time.so.
-
-**/
+*/

doc/additionalDoc/tracerdoc.h

 /**
 \page tracerdoc Tracer
-\section description Description
+\section tracerdoc_description Description
 The \b Tracer entity monitors a set of signals. With an input change on the entity's [trigger] signal,
 the tracked signal values are recorded and traced to a file. The behavior of the trace-to-file
 function can be changed, from printing to a file immediately after recording, to printing out
 only when asked explicitly.
-\section commands Commands
+
+\section tracerdoc_commands Commands
 The \b commands that this entity exposes are:
 \code
 open, close (a file);
@@ -19,7 +20,8 @@ start, stop (traces)
 For more information on the signals exposed by this entity, please check the
 code documentation of the dynamicgraph::Tracer class.
 \n\n
-\section sample Sample usage
+
+\section tracerdoc_sample Sample usage
 The following code creates a TracerRealTime entity, then sets the tracing buffer
 size to 10MB. It then tells the tracer to create files with names of the form:
 jl_XXX.dat where XXX is the signal name, and adds a few signals after
@@ -38,10 +40,9 @@ tr.add dyn.0
 tr.add jgain.gain
 \endcode
 
-\section addi Additional information
+\section tracerdoc_addi Additional information
 See doxygen documentation for the class dynamicgraph::Tracer
 
-\section generates Generated plugin file
+\section tracerdoc_generates Generated plugin file
 tracer.dll or tracer.so.
-
-**/
+*/

doc/additionalDoc/writeGraph.h

+/**
+\page writegraphdoc Displaying the graph of entities
+\section description Description
+It is possible to view the graph of entities currently instanciated.
+The format used by dynamic-graph is dot.
+Using the python interpreter the following command
+\code
+from dynamic_graph import *
+writeGraph('/tmp/my_dynamic_graph.dot')
+\endcode
+is writing the <b>my_dynamic_graph.dot</b> in the <b>/tmp</b> directory
+
+\section fromdottopdf Viewing as a PDF file
+To view the dot file you can simply use:
+\code
+dot -Tpdf /tmp/my_dynamic_graph.dot > /tmp/my_dynamic_graph.pdf
+\endcode
+
+It provides the following output:
+\image html my_dynamic_graph.png
+
+*/