wip: add description to preferences and try to autogenerate the docs

core/include/core/scopymainwindow_api.h

@@ -56,6 +56,7 @@ class SCOPY_CORE_EXPORT ScopyMainWindow_API : public ApiObject
 	Q_INVOKABLE QStringList getToolsForPlugin(QString plugin);
 	Q_INVOKABLE QPair<QString, QVariant> getPreference(QString prfName);
 	Q_INVOKABLE QMap<QString, QVariant> getPreferences();
+	Q_INVOKABLE QVector<QString> getPreferenceDescription(QString prefName);
 	Q_INVOKABLE void setPreference(QString preName, QVariant value);
 	Q_INVOKABLE void aboutPage();
 	Q_INVOKABLE QStringList getPlugins(int idx);

core/src/scopymainwindow_api.cpp

@@ -376,6 +376,16 @@ QMap<QString, QVariant> ScopyMainWindow_API::getPreferences()
 	return prefMap;
 }
 
+QVector<QString> ScopyMainWindow_API::getPreferenceDescription(QString prefName)
+{
+	Preferences *p = Preferences::GetInstance();
+	QMap<QString, QVector<QString>> prefMap = p->getPreferencesDescriptions();
+	if(prefName != NULL) {
+		return prefMap[prefName];
+	}
+	return {};
+}
+
 void ScopyMainWindow_API::setPreference(QString prefName, QVariant value)
 {
 	Preferences *p = Preferences::GetInstance();

core/src/scopypreferencespage.cpp

@@ -158,8 +158,10 @@ QWidget *ScopyPreferencesPage::buildSaveSessionPreference()
 	QHBoxLayout *lay = new QHBoxLayout(w);
 	lay->setMargin(0);
 
-	lay->addWidget(
-		PreferencesHelper::addPreferenceCheckBox(p, "general_save_session", "Save/Load Scopy session", this));
+	lay->addWidget(PreferencesHelper::addPreferenceCheckBox(p, "general_save_session", "Save/Load Scopy session",
+								"Allow Scopy to automatically save/load the session"
+								"using .ini files into a predefined location.",
+								this));
 	lay->addSpacerItem(new QSpacerItem(40, 40, QSizePolicy::Expanding, QSizePolicy::Fixed));
 	lay->addWidget(new QLabel("Settings files location ", this));
 	QPushButton *navigateBtn = new QPushButton("Open", this);
@@ -244,43 +246,85 @@ QWidget *ScopyPreferencesPage::buildGeneralPreferencesPage()
 
 	generalSection->contentLayout()->addWidget(buildSaveSessionPreference());
 	generalSection->contentLayout()->addWidget(PreferencesHelper::addPreferenceCheckBox(
-		p, "general_save_attached", "Save/Load tool attached state", generalSection));
+		p, "general_save_attached", "Save/Load tool attached state",
+		"Allow Scopy to save the state of all instruments, whether they were "
+		"detached/attached when the application was closed, and load this "
+		"state accordingly when the application restarts.",
+		generalSection));
 	generalSection->contentLayout()->addWidget(PreferencesHelper::addPreferenceCheckBox(
-		p, "general_doubleclick_attach", "Doubleclick to attach/detach tool", generalSection));
+		p, "general_doubleclick_attach", "Doubleclick to attach/detach tool",
+		"Indicates whether double-clicking attaches instruments in the application. "
+		"Enabling this option allows the user to quickly attach instruments by "
+		"double-clicking on them.",
+		generalSection));
 	generalSection->contentLayout()->addWidget(PreferencesHelper::addPreferenceCheckBox(
-		p, "general_doubleclick_ctrl_opens_menu", "Doubleclick control buttons to open menu", generalSection));
+		p, "general_doubleclick_ctrl_opens_menu", "Doubleclick control buttons to open menu", "",
+		generalSection));
 	generalSection->contentLayout()->addWidget(PreferencesHelper::addPreferenceCheckBox(
-		p, "general_use_opengl", "Enable OpenGL plotting", generalSection));
+		p, "general_use_opengl", "Enable OpenGL plotting", "", generalSection));
 	generalSection->contentLayout()->addWidget(PreferencesHelper::addPreferenceCheckBox(
-		p, "general_use_animations", "Enable menu animations", generalSection));
+		p, "general_use_animations", "Enable menu animations", "", generalSection));
 	generalSection->contentLayout()->addWidget(PreferencesHelper::addPreferenceCheckBox(
-		p, "general_check_online_version", "Enable automatic online check for updates.", generalSection));
+		p, "general_check_online_version", "Enable automatic online check for updates.",
+		"Indicates whether the application should check for online version updates. "
+		"Enabling this option allows the application to automatically check for and "
+		"notify the user of available updates at startup.",
+		generalSection));
 	generalSection->contentLayout()->addWidget(PreferencesHelper::addPreferenceCheckBox(
 		p, "general_show_status_bar", "Enable the status bar for displaying important messages.",
+		"Indicates whether the status bar should be displayed in the application. This setting "
+		"allows the user to enable or disable the status bar, which provides information about "
+		"the current state of the application."
+		"Important messages such as connection done or alerts are displayed here.",
 		generalSection));
-	generalSection->contentLayout()->addWidget(
-		PreferencesHelper::addPreferenceCheckBox(p, "show_grid", "Show Grid", generalSection));
-	generalSection->contentLayout()->addWidget(
-		PreferencesHelper::addPreferenceCheckBox(p, "show_graticule", "Show Graticule", generalSection));
 	generalSection->contentLayout()->addWidget(PreferencesHelper::addPreferenceCheckBox(
-		p, "iiowidgets_use_lazy_loading", "Use Lazy Loading", generalSection));
+		p, "show_grid", "Show Grid",
+		"Indicates whether the plot grid is visible across the application."
+		"The user can enable or disable this in order to configure the ",
+		generalSection));
+	generalSection->contentLayout()->addWidget(PreferencesHelper::addPreferenceCheckBox(
+		p, "show_graticule", "Show Graticule",
+		"This setting allows the user to enable or disable the display of the graticule "
+		"on all the plots in the application for better signal visualization.",
+		generalSection));
 	generalSection->contentLayout()->addWidget(PreferencesHelper::addPreferenceCheckBox(
-		p, "general_use_native_dialogs", "Use native dialogs", generalSection));
+		p, "iiowidgets_use_lazy_loading", "Use Lazy Loading",
+		"Indicates whether lazy loading should be used for IIO widgets. "
+		"Enabling this option allows the application to load IIO widgets only "
+		"when they are needed, improving startup performance.",
+		generalSection));
+	generalSection->contentLayout()->addWidget(PreferencesHelper::addPreferenceCheckBox(
+		p, "general_use_native_dialogs", "Use native dialogs",
+		"Indicates whether native dialogs should be used in the application."
+		"This setting allows the user to enable or disable the use of native file "
+		"dialogs and other system dialogs within the application.",
+		generalSection));
 	QWidget *autoConnectCb = PreferencesHelper::addPreferenceCheckBox(
-		p, "autoconnect_previous", "Auto-connect to previous session", generalSection);
+		p, "autoconnect_previous", "Auto-connect to previous session", "", generalSection);
 	generalSection->contentLayout()->addWidget(autoConnectCb);
 	generalSection->contentLayout()->addWidget(PreferencesHelper::addPreferenceCombo(
-		p, "font_scale", "Font scale (EXPERIMENTAL)", {"1", "1.15", "1.3", "1.45", "1.6", "1.75", "1.9"},
-		generalSection));
+		p, "font_scale", "Font scale (EXPERIMENTAL)",
+		"Scale factor for the font size used across the application, suitable for "
+		"different display settings",
+		{"1", "1.15", "1.3", "1.45", "1.6", "1.75", "1.9"}, generalSection));
 	generalSection->contentLayout()->addWidget(PreferencesHelper::addPreferenceCombo(
-		p, "general_theme", "Theme", Style::GetInstance()->getThemeList(), generalSection));
+		p, "general_theme", "Theme",
+		"Theme setting for the application interface."
+		"The user can choose between Harmonic style (light or dark) or Scopy style.",
+		Style::GetInstance()->getThemeList(), generalSection));
 	generalSection->contentLayout()->addWidget(PreferencesHelper::addPreferenceCombo(
-		p, "general_language", "Language", t->getLanguages(), generalSection));
-	generalSection->contentLayout()->addWidget(
-		PreferencesHelper::addPreferenceCheckBox(p, "general_connect_to_multiple_devices",
-							 "Connect to multiple devices (EXPERIMENTAL)", generalSection));
+		p, "general_language", "Language",
+		"Language setting for the application interface."
+		"Multiple options available, check out the documentation if a new language is needed",
+		t->getLanguages(), generalSection));
+	generalSection->contentLayout()->addWidget(PreferencesHelper::addPreferenceCheckBox(
+		p, "general_connect_to_multiple_devices", "Connect to multiple devices (EXPERIMENTAL)",
+		"Allows the application to connect to multiple devices simultaneously, providing a mechanism "
+		"to handle them separately using different sections in the left side menu."
+		"Due to not being tested using enough scenarios it is still marked as an experimental feature.",
+		generalSection));
 	generalSection->contentLayout()->addWidget(PreferencesHelper::addPreferenceCheckBox(
-		p, "general_scan_for_devices", "Regularly scan for new devices", generalSection));
+		p, "general_scan_for_devices", "Regularly scan for new devices", "", generalSection));
 
 	// Auto-connect
 	m_autoConnectWidget = new MenuSectionCollapseWidget("Session devices", MenuCollapseSection::MHCW_NONE,
@@ -310,10 +354,15 @@ QWidget *ScopyPreferencesPage::buildGeneralPreferencesPage()
 	lay->addWidget(debugWidget);
 	lay->addSpacerItem(new QSpacerItem(0, 0, QSizePolicy::Minimum, QSizePolicy::Expanding));
 
-	debugSection->contentLayout()->addWidget(
-		PreferencesHelper::addPreferenceCheckBox(p, "general_show_plot_fps", "Show plot FPS", debugSection));
+	debugSection->contentLayout()->addWidget(PreferencesHelper::addPreferenceCheckBox(
+		p, "general_show_plot_fps", "Show plot FPS",
+		"Indicates whether the frames per second should be displayed in plots "
+		"across the entire application.",
+		debugSection));
 	debugSection->contentLayout()->addWidget(PreferencesHelper::addPreferenceCombo(
-		p, "general_plot_target_fps", "Plot target FPS", {"15", "20", "30", "60"}, debugSection));
+		p, "general_plot_target_fps", "Plot target FPS",
+		"Select the Frames per second value for rendering plots in the entire application.",
+		{"15", "20", "30", "60"}, debugSection));
 	debugSection->contentLayout()->addWidget(buildResetScopyDefaultButton());
 
 	return page;

docs/gen_prefs.js

@@ -0,0 +1,30 @@
+function main() {
+    var prefs = scopy.getPreferences();
+    var keys = Object.keys(prefs);
+    var rst_data = "";
+    var output_rst_file = "preferences_table.rst";
+    rst_data += "Preferences\n";
+    rst_data += "===========\n\n";
+    rst_data += ".. list-table::\n";
+    rst_data += "   :header-rows: 1\n";
+    rst_data += "   :widths: 20 30 50\n\n";
+    rst_data += "   * - PreferenceId\n";
+    rst_data += "     - Title\n";
+    rst_data += "     - Description\n";
+
+    keys.forEach(element => {
+        var prefsDetails = scopy.getPreferenceDescription(element);
+        if (prefsDetails === undefined) {
+            printToConsole("Error: Preference details not found for " + element);
+        }
+        var title = (prefsDetails[0] !== undefined )? prefsDetails[0] : "---";
+        var description = (prefsDetails[1] !== undefined )? prefsDetails[1] : "---";
+        rst_data += "   * - " + element + "\n";
+        rst_data += "     - " + title + "\n";
+        rst_data += "     - " + description + "\n";
+    });
+    fileIO.writeToFile(rst_data, output_rst_file);
+    printToConsole("Documentation has been generated in " + output_rst_file);
+}
+
+main()

docs/user_guide/preferences.rst

@@ -0,0 +1,26 @@
+.. _preferences:
+
+=============================================
+Scopy Preferences
+=============================================
+
+.. image:: https://raw.githubusercontent.com/analogdevicesinc/scopy/doc_resources/resources/scopy-general-prefs.png
+    :align: center
+..
+
+  Scopy Preferences can be accessed using the bottom left side **preferences
+  button**. On the right side of the page, preferences for each plugin
+  are available. More details can be found in their specific plugin
+  documentation section.
+
+  The **Open** button will try to open the specific OS explorer in 
+  order to find the preference storage file.
+
+  Clicking the **Reset Scopy** button will reset the application to a default
+  configuration.
+
+  Changing some of the listed preferences will require an application
+  restart. More details on each preference are listed below.
+
+.. include:: preferences_table.rst
+

gui/include/gui/preferenceshelper.h

@@ -40,12 +40,13 @@ class SCOPY_GUI_EXPORT PreferencesHelper
 {
 
 public:
-	static QWidget *addPreferenceCheckBox(Preferences *p, QString id, QString description,
+	static QWidget *addPreferenceCheckBox(Preferences *p, QString id, QString title, QString description,
 					      QObject *parent = nullptr);
-	static QWidget *addPreferenceEdit(Preferences *p, QString id, QString description, QObject *parent = nullptr);
-	static QWidget *addPreferenceCombo(Preferences *p, QString id, QString description, QStringList options,
-					   QObject *parent = nullptr);
-	static QWidget *addPreferenceComboList(Preferences *p, QString id, QString description,
+	static QWidget *addPreferenceEdit(Preferences *p, QString id, QString title, QString description,
+					  QObject *parent = nullptr);
+	static QWidget *addPreferenceCombo(Preferences *p, QString id, QString title, QString description,
+					   QStringList options, QObject *parent = nullptr);
+	static QWidget *addPreferenceComboList(Preferences *p, QString id, QString title, QString description,
 					       QList<QPair<QString, QVariant>> options, QObject *parent);
 };
 } // namespace scopy

gui/src/preferenceshelper.cpp

@@ -26,7 +26,8 @@
 #include <smallOnOffSwitch.h>
 
 using namespace scopy;
-QWidget *PreferencesHelper::addPreferenceCheckBox(Preferences *p, QString id, QString description, QObject *parent)
+QWidget *PreferencesHelper::addPreferenceCheckBox(Preferences *p, QString id, QString title, QString description,
+						  QObject *parent)
 {
 	QWidget *widget = new QWidget();
 	QHBoxLayout *layout = new QHBoxLayout();
@@ -39,17 +40,20 @@ QWidget *PreferencesHelper::addPreferenceCheckBox(Preferences *p, QString id, QS
 	pref->setChecked(p->get(id).toBool());
 	parent->connect(pref, &SmallOnOffSwitch::toggled, parent, [p, id](bool b) { p->set(id, b); });
 
+	p->initDescription(id, title, description);
+
 	QSpacerItem *space = new QSpacerItem(20, 20, QSizePolicy::Fixed, QSizePolicy::Fixed);
 
-	layout->addWidget(new QLabel(description, widget));
+	layout->addWidget(new QLabel(title, widget));
 	layout->addSpacerItem(space);
 	layout->addWidget(pref);
 	widget->setSizePolicy(QSizePolicy::Fixed, QSizePolicy::Fixed);
 
 	return widget;
 }
 
-QWidget *PreferencesHelper::addPreferenceEdit(Preferences *p, QString id, QString description, QObject *parent)
+QWidget *PreferencesHelper::addPreferenceEdit(Preferences *p, QString id, QString title, QString description,
+					      QObject *parent)
 {
 	QWidget *widget = new QWidget();
 	QHBoxLayout *layout = new QHBoxLayout();
@@ -63,7 +67,8 @@ QWidget *PreferencesHelper::addPreferenceEdit(Preferences *p, QString id, QStrin
 	pref->setText(pref1Val);
 	parent->connect(pref, &QLineEdit::textChanged, parent, [p, id](QString b) { p->set(id, b); });
 
-	QLabel *label = new QLabel(description);
+	QLabel *label = new QLabel(title);
+	p->initDescription(id, title, description);
 
 	QSpacerItem *space = new QSpacerItem(20, 20, QSizePolicy::Preferred, QSizePolicy::Preferred);
 
@@ -73,7 +78,7 @@ QWidget *PreferencesHelper::addPreferenceEdit(Preferences *p, QString id, QStrin
 	return widget;
 }
 
-QWidget *PreferencesHelper::addPreferenceComboList(Preferences *p, QString id, QString description,
+QWidget *PreferencesHelper::addPreferenceComboList(Preferences *p, QString id, QString title, QString description,
 						   QList<QPair<QString, QVariant>> options, QObject *parent)
 {
 	QWidget *w = new QWidget();
@@ -82,7 +87,8 @@ QWidget *PreferencesHelper::addPreferenceComboList(Preferences *p, QString id, Q
 	lay->setSpacing(0);
 	lay->setMargin(0);
 	w->setLayout(lay);
-	QLabel *lab = new QLabel(description);
+	QLabel *lab = new QLabel(title);
+	p->initDescription(id, title, description);
 	QSpacerItem *space = new QSpacerItem(20, 20, QSizePolicy::Preferred, QSizePolicy::Preferred);
 	QString pref1Val;
 
@@ -106,15 +112,16 @@ QWidget *PreferencesHelper::addPreferenceComboList(Preferences *p, QString id, Q
 	return w;
 }
 
-QWidget *PreferencesHelper::addPreferenceCombo(Preferences *p, QString id, QString description, QStringList options,
-					       QObject *parent)
+QWidget *PreferencesHelper::addPreferenceCombo(Preferences *p, QString id, QString title, QString description,
+					       QStringList options, QObject *parent)
 {
 	QWidget *w = new QWidget();
 	QHBoxLayout *lay = new QHBoxLayout();
 	lay->setSpacing(0);
 	lay->setMargin(0);
 	w->setLayout(lay);
-	QLabel *lab = new QLabel(description);
+	QLabel *lab = new QLabel(title);
+	p->initDescription(id, title, description);
 	QSpacerItem *space = new QSpacerItem(20, 20, QSizePolicy::Preferred, QSizePolicy::Preferred);
 	QString pref1Val = p->get(id).toString();
 	QComboBox *pref = new QComboBox();

pluginbase/include/pluginbase/preferences.h

@@ -52,6 +52,18 @@ class SCOPY_PLUGINBASE_EXPORT Preferences : public QObject
 	 */
 	static void init(QString, QVariant);
 	void _init(QString, QVariant);
+
+	/**
+	 * @brief initDescription
+	 * Initialize a map with title and description for each preference
+	 * to be later used in docs and hover widgets in the Scopy prefs page.
+	 * @param k
+	 * @param title
+	 * @param description
+	 */
+	void initDescription(QString k, QString title, QString description);
+	void _initDescription(QString k, QString title, QString description);
+
 	/**
 	 * @brief clear
 	 * clears preferences table
@@ -73,6 +85,7 @@ class SCOPY_PLUGINBASE_EXPORT Preferences : public QObject
 	QMap<QString, QVariant> getPreferences() const;
 	void setPreferences(QMap<QString, QVariant> s);
 
+	QMap<QString, QVector<QString>> getPreferencesDescriptions() const;
 public Q_SLOTS:
 	/**
 	 * @brief setPreferencesFilename
@@ -109,6 +122,7 @@ public Q_SLOTS:
 
 private:
 	QMap<QString, QVariant> p;
+	QMap<QString, QVector<QString>> pDescriptions;
 	QSettings *s;
 	static Preferences *pinstance_;
 };

pluginbase/src/apiobject.cpp

@@ -31,7 +31,9 @@ using namespace scopy;
 
 ApiObject::ApiObject(QObject *parent)
 	: QObject(parent)
-{}
+{
+	qRegisterMetaType<QPair<QString, QString>>("QPair<QString, QString>");
+}
 
 ApiObject::~ApiObject() {}