From e8f4eab4b0cfdc06983180ab15d98f5b636b4679 Mon Sep 17 00:00:00 2001
From: Joseph Mirabel <jmirabel@laas.fr>
Date: Fri, 20 May 2016 17:07:10 +0200
Subject: [PATCH] Add some documentation
---
doc/Doxyfile.extra.in | 2 +
include/gepetto/gui/mainwindow.hh | 1 +
include/gepetto/gui/pythonwidget.hh | 38 ++++++++++++++++++-
include/gepetto/gui/settings.hh | 30 ++++++++++++++-
pyplugins/CMakeLists.txt | 2 +-
pyplugins/gepetto/gui/__init__.py | 2 +-
.../gui/{plugin.py => pythonwidget.py} | 5 ++-
7 files changed, 75 insertions(+), 5 deletions(-)
rename pyplugins/gepetto/gui/{plugin.py => pythonwidget.py} (96%)
diff --git a/doc/Doxyfile.extra.in b/doc/Doxyfile.extra.in
index b0c1b6c..190ce9d 100644
--- a/doc/Doxyfile.extra.in
+++ b/doc/Doxyfile.extra.in
@@ -7,3 +7,5 @@ INPUT = @CMAKE_SOURCE_DIR@/include \
TAGFILES = @GEPETTO_VIEWER_DOXYGENDOCDIR@/gepetto-viewer.doxytag=@GEPETTO_VIEWER_DOXYGENDOCDIR@
GENERATE_TREEVIEW = NO
+
+EXAMPLE_PATH = @CMAKE_SOURCE_DIR@/
diff --git a/include/gepetto/gui/mainwindow.hh b/include/gepetto/gui/mainwindow.hh
index 3ea06c6..c8a806f 100644
--- a/include/gepetto/gui/mainwindow.hh
+++ b/include/gepetto/gui/mainwindow.hh
@@ -65,6 +65,7 @@ namespace gepetto {
signals:
void sendToBackground (WorkItem* item);
void createView (QString name);
+ /// Triggered when an OSGWidget is created.
void viewCreated (OSGWidget* widget);
void refresh ();
void applyCurrentConfiguration();
diff --git a/include/gepetto/gui/pythonwidget.hh b/include/gepetto/gui/pythonwidget.hh
index 03e4de5..0691f58 100644
--- a/include/gepetto/gui/pythonwidget.hh
+++ b/include/gepetto/gui/pythonwidget.hh
@@ -17,6 +17,37 @@
namespace gepetto {
namespace gui {
+ /// \defgroup plugin Plugin interfaces
+
+
+ /// \ingroup plugin
+ /// Python plugin interface
+ ///
+ /// A Python plugin is a Python module containing a class Plugin, with a
+ /// constructor taking a pointer to the MainWindow as input.
+ ///
+ /// For instance, if you have \code gepetto.gui=true \endcode in your
+ /// configuration file, then the Plugin class will be accessed via:
+ ///
+ /// \code{py}
+ /// from gepetto.gui import Plugin
+ /// pluginInstance = Plugin(mainWindow)
+ /// \endcode
+ ///
+ /// It may interact with the interface in two following ways.
+ ///
+ /// pyplugin_dockwidget Add a dock widget:
+ ///
+ /// Your plugin may inherits from class PythonQt.QtGui.QDockWidget.
+ /// In this case, an instance of the Plugin will be added to the MainWindow
+ /// as a QDockWidget.
+ ///
+ /// pyplugin_signals Signals and slots:
+ ///
+ /// The following method will be automatically connected to Qt signals:
+ /// \li MainWindow::viewCreated(OSGWidget*) -> Plugin.osgWidget
+ ///
+ /// \sa See example \ref pyplugins/gepetto/gui/pythonwidget.py
class PythonWidget : public QDockWidget
{
Q_OBJECT
@@ -30,7 +61,7 @@ namespace gepetto {
///
/// This is mostly equivalent to running the following code in the Python
/// console
- /// \code[py]
+ /// \code{py}
/// import modulename
/// pluginInstance = modulename.Plugin(mainWindow)
/// mainWindow.addDockWidget (1, pluginInstance)
@@ -57,6 +88,11 @@ namespace gepetto {
public slots:
void browseFile();
};
+
+ /// \example pyplugins/gepetto/gui/pythonwidget.py
+ /// This is an example Python Plugin for \link hpp::gui::PythonWidget \endlink. Two classes are defined:
+ /// \b _NodeCreator and \b Plugin. Two signals are used: \a mainWindow.refresh()
+ /// and \a osgWidget.
} // namespace gui
} // namespace gepetto
diff --git a/include/gepetto/gui/settings.hh b/include/gepetto/gui/settings.hh
index 8015797..cc8c46e 100644
--- a/include/gepetto/gui/settings.hh
+++ b/include/gepetto/gui/settings.hh
@@ -12,6 +12,12 @@ namespace gepetto {
namespace gui {
class MainWindow;
+ /// Settings manager for the interface.
+ ///
+ /// This struct is responsible for parsing configuration files as follow:
+ /// - Robots file: Settings::readRobotFile()
+ /// - Environments file: Settings::readEnvFile()
+ /// - Configuration file: Settings::readSettingFile()
struct Settings {
std::string configurationFile;
std::string predifinedRobotConf;
@@ -52,11 +58,33 @@ namespace gepetto {
std::ostream& print (std::ostream& os);
- private:
+ /// \note Prefer using Settings::fromFiles()
void readRobotFile ();
+ /// \note Prefer using Settings::fromFiles()
void readEnvFile ();
+ /// Read the settings file.
+ ///
+ /// Here is the syntax:
+ /// \code
+ /// ; Comments starts with a ; You may uncomment to see the effect.
+ ///
+ /// [plugins]
+ /// ; Put a list of C++ plugins followed by '=true'. For instance, HPP users may have
+ /// ; libhppwidgetsplugin.so=true
+ /// ; libhppcorbaserverplugin.so=true
+ ///
+ /// [pyplugins]
+ /// ; Put a list of Python plugins followed by '=true'. For instance, the example plugin can be loaded with
+ /// ; gepetto.plugin=true
+ ///
+ /// ; WARNING: Any comment in this file may be removed by the GUI if you regenerate a configuration file.
+ /// \endcode
+ /// \note Details on plugin interface can be found in PluginInterface, resp. PythonWidget, class
+ /// for C++, resp. Python, plugins.
+ /// \note Prefer using Settings::fromFiles()
void readSettingFile ();
+ private:
void writeRobotFile ();
void writeEnvFile ();
void writeSettingFile ();
diff --git a/pyplugins/CMakeLists.txt b/pyplugins/CMakeLists.txt
index 786e239..d1404b0 100644
--- a/pyplugins/CMakeLists.txt
+++ b/pyplugins/CMakeLists.txt
@@ -17,7 +17,7 @@
INSTALL(
FILES
- ${CMAKE_CURRENT_SOURCE_DIR}/gepetto/gui/plugin.py
+ ${CMAKE_CURRENT_SOURCE_DIR}/gepetto/gui/pythonwidget.py
${CMAKE_CURRENT_SOURCE_DIR}/gepetto/gui/__init__.py
DESTINATION ${PYTHON_SITELIB}/gepetto/gui
)
diff --git a/pyplugins/gepetto/gui/__init__.py b/pyplugins/gepetto/gui/__init__.py
index 1cdff06..2854c2e 100644
--- a/pyplugins/gepetto/gui/__init__.py
+++ b/pyplugins/gepetto/gui/__init__.py
@@ -1 +1 @@
-from plugin import Plugin
+from pythonwidget import Plugin
diff --git a/pyplugins/gepetto/gui/plugin.py b/pyplugins/gepetto/gui/pythonwidget.py
similarity index 96%
rename from pyplugins/gepetto/gui/plugin.py
rename to pyplugins/gepetto/gui/pythonwidget.py
index a6c362d..e7d1264 100644
--- a/pyplugins/gepetto/gui/plugin.py
+++ b/pyplugins/gepetto/gui/pythonwidget.py
@@ -58,7 +58,10 @@ class _NodeCreator (QtGui.QWidget):
self.client.gui.addToGroup(str(self.nodeName.text), str(self.groupNodes.currentText))
class Plugin(QtGui.QDockWidget):
- """ Example of plugin of the Gepetto Viewer GUI """
+ """
+ Example of plugin of the Gepetto Viewer GUI. This can interact with
+ PythonWidget C++ class.
+ """
def __init__ (self, mainWindow, flags = None):
if flags is None:
super(Plugin, self).__init__ ("Gepetto Viewer plugin", mainWindow)
--
GitLab