From 52ebaecc68d1d190c526c2f5b7c9bb44158223db Mon Sep 17 00:00:00 2001
From: Olivier Stasse <ostasse@laas.fr>
Date: Thu, 28 Feb 2019 08:06:14 +0100
Subject: [PATCH] [doc] Update documentation on debugging. Structural
modification of the documentation to make it clearer.
---
doc/additionalDoc/debug-doc.h | 10 +++
doc/additionalDoc/debug-trace-doc.h | 72 ++++++++++++++++++
doc/additionalDoc/debug.h | 10 ---
doc/additionalDoc/extension.h | 38 ++++++++++
doc/additionalDoc/graph.h | 2 +-
doc/additionalDoc/installation.h | 35 +++++++++
doc/additionalDoc/introduction.h | 65 ++++++++++++++++
doc/additionalDoc/package.h | 110 +++-------------------------
doc/additionalDoc/references.h | 21 ++++++
9 files changed, 252 insertions(+), 111 deletions(-)
create mode 100644 doc/additionalDoc/debug-doc.h
create mode 100644 doc/additionalDoc/debug-trace-doc.h
delete mode 100644 doc/additionalDoc/debug.h
create mode 100644 doc/additionalDoc/extension.h
create mode 100644 doc/additionalDoc/installation.h
create mode 100644 doc/additionalDoc/introduction.h
create mode 100644 doc/additionalDoc/references.h
diff --git a/doc/additionalDoc/debug-doc.h b/doc/additionalDoc/debug-doc.h
new file mode 100644
index 0000000..381bcf9
--- /dev/null
+++ b/doc/additionalDoc/debug-doc.h
@@ -0,0 +1,10 @@
+/**
+\page debug Debugging
+
+They are several ways to perform debugging in dynamic-graph depending on your needs or situation:
+- If you just need to collect informations from signals (like rosbag). You can use
+an entity called Tracer inside the graph:\subpage tracerdoc
+- programmatically in C++ with macros \subpage subp_dbg_trace
+- programmatically inside the entity in C++ using member of the entities:
+\subpage tracerrealtimedoc
+**/
diff --git a/doc/additionalDoc/debug-trace-doc.h b/doc/additionalDoc/debug-trace-doc.h
new file mode 100644
index 0000000..ba90693
--- /dev/null
+++ b/doc/additionalDoc/debug-trace-doc.h
@@ -0,0 +1,72 @@
+/**
+\page subp_dbg_trace Debugging with macros and level
+
+\section subp_dbg_trace_intro Introduction
+The idea of this class and collection of MACROS is to specify
+a level for a message, and record the message in a stream according to this level.
+In addition there are mechanisms allowing that no time
+is wasted in condition test. You can therefore let the debugging messages
+inside the code without impact on performances.
+
+\section subp_dbg_trace_set_on_macros Setting up dgDEBUG macros
+
+To allow message display the entity must be compiled with the macro
+\code
+#define VP_DEBUG 1
+\endcode
+Commenting or removing this macro disable all the messages specified
+by the following macros.
+
+The level up to which the messages are accepted for display is
+specified by:
+\code
+#define VP_DEBUG_MODE 50
+\endcode
+
+In the constructor of the entity, the file where all the messages
+are written is specified by:
+\code
+ dynamicgraph::dgDEBUGFLOW.openFile("/tmp/dynamic-graph-traces.txt");
+\endcode
+
+\section subp_dbg_trace_using_macros Using dgDEBUG macros
+
+To print that the beginning of a method is being executed use the following macros:
+\code
+ dgDEBUGIN(5);
+\endcode
+5 here specifies the minimum level that you be specified by VP_DEBUG_MODE for this message
+to be displayed.
+
+It will generate the following output:
+\code
+/path_to/dynamic-graph/tests/debug-trace.cpp: testDebugTrace(#46) :# In {
+\endcode
+The output displays the name of the source file, the name of the method,
+the line where is the macro, and the message itself.
+
+When going out of the method:
+\code
+ dgDEBUGOUT(5);
+\endcode
+
+This generates the following output:
+\code
+/path_to/dynamic-graph/tests/debug-trace.cpp: testDebugTrace(#54) :# Out }
+\endcode
+
+A message inside the code is written through:
+\code
+ dgDEBUG(5) << "Here is a test" << std::endl;
+\endcode
+
+This generates the following output:
+\code
+/path_to/dynamic-graph/tests/debug-trace.cpp: testDebugTrace(#52) :Here is a test
+\endcode
+
+\section subp_dbg_trace_wrk_exp Working example
+
+A full working example is given here:
+\include ../tests/debug-trace.cpp
+ */
diff --git a/doc/additionalDoc/debug.h b/doc/additionalDoc/debug.h
deleted file mode 100644
index 38fa067..0000000
--- a/doc/additionalDoc/debug.h
+++ /dev/null
@@ -1,10 +0,0 @@
-/**
-\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
-**/
diff --git a/doc/additionalDoc/extension.h b/doc/additionalDoc/extension.h
new file mode 100644
index 0000000..d3f9412
--- /dev/null
+++ b/doc/additionalDoc/extension.h
@@ -0,0 +1,38 @@
+/**
+\page subp_how_to_use Using this package
+
+\section usecase How to use this package
+
+\subsection use_programmatically General introduction
+Objects, which are derived from Entities (base class dynamicgraph::Entity), can be
+declared within the code and compiled to shared libraries (.so/.dll files).
+These libraries can be loaded at run-time using the PluginLoader methods,
+and at the same time register their class names to the Factory (see the
+examples in the <a href="http://projects.laas.fr/gepetto/doc/stack-of-tasks/sot-core/master/doxygen-html">sot-core documentation</a>
+for advanced control examples).
+
+The Factory can then create instances of these objects and subsequently
+register them in the Pool, where they can be listed, accessed, and acted upon
+(see PoolStorage documentation). Basic commands defined by entities include
+signal connection graph file generation, help and name print, and signals.
+This is usually done through a scripting language such as python (see
+<a hef="https://github.com/stack-of-tasks/dynamic-graph-python">dynamic-graph-python</a>)
+
+The singletons made available by including the corresponding headers in this
+module are:
+\li dynamicgraph::FactoryStorage
+\li dynamicgraph::PoolStorage
+
+For an example of a program creating entities in C++, see the unit test
+test_pool.cpp (in your package source directory/tests).
+
+\subsection Tutorial
+A tutorial is available <a href="http://stack-of-tasks.github.io/dynamic-graph-tutorial/">here</a>
+
+\section sec_htw_helpers Helpers
+
+When writing entities you might use some macros which are very useful to write your class.
+They are given also in the <a href="http://projects.laas.fr/gepetto/doc/stack-of-tasks/sot-core/master/doxygen-html">sot-core</a> package as well.
+
+
+*/
diff --git a/doc/additionalDoc/graph.h b/doc/additionalDoc/graph.h
index 09bbb4b..cf567dc 100644
--- a/doc/additionalDoc/graph.h
+++ b/doc/additionalDoc/graph.h
@@ -1,5 +1,5 @@
/**
-\page page_graph Graph
+\page p_graph Graph
In this package, the graph considered are directed graphs.
diff --git a/doc/additionalDoc/installation.h b/doc/additionalDoc/installation.h
new file mode 100644
index 0000000..e0e1460
--- /dev/null
+++ b/doc/additionalDoc/installation.h
@@ -0,0 +1,35 @@
+/**
+\page subp_installation Installation
+
+\section sec_inst_dep Dependencies
+
+dynamic-graph depends on:
+<ul>
+<li> boost </li>
+<li> eigen </li>
+<li> cmake </li>
+</ul>
+
+\section sec_inst_get_src Getting the source
+
+The sources are available through github at the following URL:
+<a href="https://github.com/stack-of-tasks/dynamic-graph">https://github.com/stack-of-tasks/dynamic-graph</a>
+
+To clone:
+\code
+git clone https://github.com/stack-of-tasks/dynamic-graph.git
+\endcode
+
+
+\section sec_inst_comp Compiling
+
+\code
+cd dynamic-graph
+mkdir _build
+cd _build
+cmake .. -DCMAKE_BUILD_TYPE=RELEASE
+make
+\endcode
+
+
+*/
diff --git a/doc/additionalDoc/introduction.h b/doc/additionalDoc/introduction.h
new file mode 100644
index 0000000..c24ac33
--- /dev/null
+++ b/doc/additionalDoc/introduction.h
@@ -0,0 +1,65 @@
+/**
+\page subp_concept_intro General introduction
+\section intro_dynamicGraph Introduction
+
+The dynamic-graph package is used to connect computation nodes, "entities"
+together using a graph system, akin to what Simulink does. Entities are connected
+through input and output signals.
+With the building blocks this package provides, you can easily create a full computation graph
+for a given problem. It is the basis for the stack of tasks operation.
+
+
+\subsection controlgraph Exemple: Real-time control
+
+<p>To give a more concrete example, the real-time control used by the Gepetto group for the humanoid robot HRP-2
+is detailled.</p>
+<p>
+Real-time control system are usually driven by a cyclic computational node which
+needs to send a control reference value to each motors of a robot. To compute this
+control reference values, sensor values need to be provided.
+In the Stack-Of-Tasks special entities called Device are used to
+provide an abstract interface to the hardware.</p>
+A scheme of the real-time control graph used for the humanoid robot HRP-2 is depicted in the following figure:
+
+\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
+figure.
+In the SoT framework it is often cast as an optimization problem.
+This optimization problem is build using a control "Task" (not to be confused with the
+general word task). A control "Task" regulates the difference with a "Feature" computed
+on the current robot state and a "Desired Feature". For instance when walking, the regulated
+feature is the robot's Center-Of-Mass (CoM) position. The "Feature" is computed using a
+library using the robot model and the sensor value. The entity making this computation is "Dyn".
+A walking pattern generator using foot-steps position given in advance generates the desired
+value for the CoM.
+Note that the "Dyn" entity uses the sensor provided by the entity "Robot". </p>
+
+<p>
+From a pure computer science viewpoint we wish to avoid recomputing data such as articular Jacobians
+when this is unnecessary. Therefore the data generated by an entity through signals may have two types of
+dependencies: one dependency related to time and dependencies on other signals. Internally an entity
+does not recompute the data if no new information is available, it is simply providing the same information
+computed before. Please note that this package provides only the computational framework to realize
+the data dependency and the entities. Solvers, libraries to compute mechanical quantities are provided
+in different packages.
+</p>
+
+<p>
+Finally in order to dynamically create a graph, it is possible \b on-line to load classes of entities and
+create instances of entities.</p>
+
+\subsection Functionnalities
+
+\li Support for extensions and modules using dynamic link libraries
+\li Template-based signal definition, independent
+\li Type-safe connection of input and output signals
+\li On-demand signal computation as well as a caching system for signal values allow fast
+computation of signal values, which is a critical point for real-time systems\n
+See \ref scriptingabout
+
+*/
diff --git a/doc/additionalDoc/package.h b/doc/additionalDoc/package.h
index f419e68..95071b7 100644
--- a/doc/additionalDoc/package.h
+++ b/doc/additionalDoc/package.h
@@ -22,108 +22,18 @@
/**
\mainpage
+The dynamic-graph aims at building computational graphs for real-time control.
+It provides the basic software functionnalities.
+A more detailed introduction is available at \subpage subp_concept_intro.
-\section intro_dynamicGraph Introduction
-
-The dynamic-graph package is used to connect computation nodes, "entities"
-together using a graph system, akin to what Simulink does. Entities are connected
-through input and output signals.
-With the building blocks this package provides, you can easily create a full computation graph
-for a given problem. It is the basis for the stack of tasks operation.
-
-
-\subsection controlgraph Exemple: Real-time control
-
-<p>To give a more concrete example, the real-time control used by the Gepetto group for the humanoid robot HRP-2
-is detailled.</p>
-<p>
-Real-time control system are usually driven by a cyclic computational node which
-needs to send a control reference value to each motors of a robot. To compute this
-control reference values, sensor values need to be provided.
-In the Stack-Of-Tasks special entities called Device are used to
-provide an abstract interface to the hardware.</p>
-A scheme of the real-time control graph used for the humanoid robot HRP-2 is depicted in the following figure:
-
-\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
-figure.
-In the SoT framework it is often cast as an optimization problem.
-This optimization problem is build using a control "Task" (not to be confused with the
-general word task). A control "Task" regulates the difference with a "Feature" computed
-on the current robot state and a "Desired Feature". For instance when walking, the regulated
-feature is the robot's Center-Of-Mass (CoM) position. The "Feature" is computed using a
-library using the robot model and the sensor value. The entity making this computation is "Dyn".
-A walking pattern generator using foot-steps position given in advance generates the desired
-value for the CoM.
-Note that the "Dyn" entity uses the sensor provided by the entity "Robot". </p>
-
-<p>
-From a pure computer science viewpoint we wish to avoid recomputing data such as articular Jacobians
-when this is unnecessary. Therefore the data generated by an entity through signals may have two types of
-dependencies: one dependency related to time and dependencies on other signals. Internally an entity
-does not recompute the data if no new information is available, it is simply providing the same information
-computed before. Please note that this package provides only the computational framework to realize
-the data dependency and the entities. Solvers, libraries to compute mechanical quantities are provided
-in different packages.
-</p>
-
-<p>
-Finally in order to dynamically create a graph, it is possible \b on-line to load classes of entities and
-create instances of entities.</p>
-
-\subsection Functionnalities
-
-\li Support for extensions and modules using dynamic link libraries
-\li Template-based signal definition, independent
-\li Type-safe connection of input and output signals
-\li On-demand signal computation as well as a caching system for signal values allow fast
-computation of signal values, which is a critical point for real-time systems\n
-See \ref scriptingabout
-
-
-
-
-\section usecase How to use this package
-\subsection use_programmtically Programmatically
-Objects, which are derived from Entities (base class dynamicgraph::Entity), can be
-declared within the code and compiled to shared libraries (.so/.dll files).
-These libraries can be loaded at run-time using the PluginLoader methods,
-and at the same time register their class names to the Factory (see the
-examples in the SOT documentation to learn how).
-
-The Factory can then create instances of these objects and subsequently
-register them in the Pool, where they can be listed, accessed, and acted upon
-(see PoolStorage documentation). Basic commands defined by entities include
-signal connection graph file generation, help and name print, and signals.
-
-The singletons made available by including the corresponding headers in this
-module are:
-\li dynamicgraph::FactoryStorage
-\li dynamicgraph::PoolStorage
-
-For an example of a program creating entities in C++, see the unit test
-test_pool.cpp (in your package source directory/unitTesting).
-
-\subsection Tutorial
-A tutorial is available <a href="http://stack-of-tasks.github.io/dynamic-graph-tutorial/">here</a>
-\section references References
-\anchor Mansard2009
-
-<b> "A versatile Generalized Inverted Kinematics implementation for collaborative working humanoid robots: The Stack Of Tasks"</b>,
-<em>N. Mansard, O. Stasse, P. Evrard, A. Kheddar,</em>
-Int. Conf. on Autonomous Robots, ICAR, 2009
-
-\anchor Mansard2007
-
-<b>"Task sequencing for sensor-based control"</b>,
-<em>N. Mansard, F. Chaumette,</em>
-IEEE Trans. on Robotics, 23(1):60-72, February 2007
+The installation instruction are given at \subpage subp_installation.
+
+The software graph structure is detailled in \subpage p_graph
+
+For debugging your entities detailed instructions are given in \subpage debug
+
+For citing the software in your research work please refer to \subpage subp_references
\namespace dynamicgraph This is the namespace where every object and class of this library is located.
diff --git a/doc/additionalDoc/references.h b/doc/additionalDoc/references.h
new file mode 100644
index 0000000..e360c2a
--- /dev/null
+++ b/doc/additionalDoc/references.h
@@ -0,0 +1,21 @@
+/**
+\page subp_references References
+
+\section sec_refer References
+Please when referencing the Stack-Of-Tasks use the following reference:
+
+\anchor Mansard2009
+
+<b> <a href="https://hal-lirmm.ccsd.cnrs.fr/lirmm-00796736/document">
+"A versatile Generalized Inverted Kinematics implementation for collaborative working humanoid robots: The Stack Of Tasks"</a>
+</b>,
+<em>N. Mansard, O. Stasse, P. Evrard, A. Kheddar,</em>
+Int. Conf. on Autonomous Robots, ICAR, 2009
+
+\anchor Mansard2007
+
+<b>"Task sequencing for sensor-based control"</b>,
+<em>N. Mansard, F. Chaumette,</em>
+IEEE Trans. on Robotics, 23(1):60-72, February 2007
+
+*/
--
GitLab