[Doc] Update documentation

doc/qdoc/common.qdocconf

@@ -17,18 +17,23 @@ codesuffix         = "\n"
 
 # override/add some things to the stylesheets:
 HTML.stylesheets  += ./pm.css
+# the above does not acutally add the stylesheet to the html file, so do it
+# manually here. Include the default first.
+HTML.headerstyles = \
+    "  <link rel=\"stylesheet\" type=\"text/css\" href=\"style/offline.css\" />\n" \
+    "  <link rel=\"stylesheet\" type=\"text/css\" href=\"style/pm.css\" />\n"
 
 # assign custom HTML footer to replace Qt's default copyright notice
 HTML.footer = "<div align='center'><hr/>" \
               "<p><small>Patchmanager Documentation\n" \
-              "Copyright (c) 2023 Patchmanager for SailfishOS contributors.\n" \
+              "Copyright (c) 2023,2024 Patchmanager for SailfishOS contributors.\n" \
               "This document may be used under the terms of the " \
               "<a href='https://spdx.org/licenses/CC-BY-SA-4.0.html'>" \
               "Creative Commons Attribution Share Alike 4.0 International</a> " \
               "License.</small></p>" \
               "<p/></div>"
 
-navigation.homepage = https://github.com/sailfishos-patches/patchmanager/wiki
+navigation.homepage = Documentation Home
 navigation.hometitle = Patchmanager
 navigation.landingpage = Patchmanager Documentation
 

doc/qdoc/daemon.qdocconf

@@ -4,7 +4,9 @@ versionsym      =
 version         = 2.0
 url             = https://github.com/sailfishos-patches/patchmanager
 
-include (common.qdocconf)
+include(common.qdocconf)
+depends += qtcore qtdbus qtnetwork
+depends += patchmanager qml-plugin
 
 headerdirs += ../../src/bin/patchmanager-daemon
 headers.fileextensions = "*.h *.hpp"

doc/qdoc/dialog.qdocconf

@@ -4,7 +4,10 @@ versionsym      =
 version         = 2.0
 url             = https://github.com/sailfishos-patches/patchmanager
 
-include (common.qdocconf)
+include(common.qdocconf)
+
+depends += qtdbus qtnetwork
+depends += patchmanager daemon qml-plugin
 
 sourcedirs = ../../src/bin/dialog
 

doc/qdoc/general.qdocconf

@@ -1,10 +1,18 @@
 project = patchmanager
 description = Patchmanager
 
-include (common.qdocconf)
+include(common.qdocconf)
+
+depends += daemon qml-plugin settings-plugin preload dialog
 
 ## Sources
-sources += ../../src/index.qdoc
-# for quoting
-exampledirs += ../../src/bin/patchmanager-daemon
+sources += ../../src/index.qdoc \
+           ../../src/patchdev.qdoc \
+           ../../src/user.qdoc \
+           ../../src/externalpages.qdoc
+# for quoting. WARNING: Setting this wrong, e.g. to
+# ../../src/bin/patchmanager-daemon will cause qdoc to create double index.html
+# files at the wrong place.
+# So, only give paths where the actual files reside:
+exampledirs += ../../src/bin/patchmanager-daemon/dbus
 

doc/qdoc/plugin.qdocconf

@@ -4,7 +4,9 @@ versionsym      =
 version         = 2.0
 url             = https://github.com/sailfishos-patches/patchmanager
 
-include (common.qdocconf)
+include(common.qdocconf)
+
+depends += qml-plugin
 
 sourcedirs = ../../src/plugin
 

doc/qdoc/pm.css

@@ -1,5 +1,82 @@
-a:link { color: #8C001A; text-decoration: none; text-align: left; }
+:root {
+    /* define our own custom color palette. Colors generated by some online
+     * tool using the Patchmanager icon.
+
+       "Pflaster" means band-aid in German.
+     */
+    --black: #000000ff;
+    --pm-pflaster-light: #efd1b3ff;
+    --pm-pflaster-medium-1: #dda267ff;
+    --pm-pflaster-medium-2: #dda267ff;
+    --pm-pflaster-darker: #ad7e52ff;
+    --pm-pflaster-dark: #584029ff;
+    --pm-red: #EF1C10ff;
+    --pm-green: #66BC52ff;
+    --pm-gray-lightest: ##f1f3f2ff;
+    --pm-gray-light-1: #d6dcd7ff;
+    --pm-gray-light-2: #b8c9c5ff;
+    --pm-gray-medium-1: #96a9a1ff;
+    --pm-gray-medium-2: #71928aff;
+    --pm-gray-dark: #2d3a37ff;
+
+  color: var(--pm-pflaster-dark);
+  background-color: var(--pm-gray-lightest);
+}
+html {
+  color: var(--pm-pflaster-dark);
+    background-color: var(--pm-gray-lightest);
+}
+
+body {
+    margin-left: 3vw; margin-right: 3vw;
+    font-family: "Segoe UI", "Noto Sans", Helvetica, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji";
+}
+code {
+    font-family: SFMono-Regular, "SF Mono", Menlo, Consolas, "Liberation Mono", monospace;
+    font-weight: medium;
+}
 a.qa-mark:target:before { content: "***"; color: #ff0000; }
-a:hover { color: #8C0060; text-align: left; }
-a:visited { color: #8C001A; text-align: left; }
-a:visited:hover { color: #8C0060; text-align: left; }
+a:link { color: var(--pm-pflaster-darker); text-decoration: none; text-align: left; }
+a:active { color: var(--pm-red); text-align: left; }
+a:active:hover { text-decoration: underline; }
+
+.content a:visited { color: var(--pm-green); text-align: left; }
+.content a:visited:hover { text-decoration: underline; }
+span.type a:visited { text-decoration: underline; }
+
+.red { color: var(--pm-red); }
+
+/*
+a:visited { color: var(--pm-pflaster-dark); text-align: left; }
+a:active { color: var(--pm-green); text-align: left; }
+
+*/
+
+.header .breadcrumb { background-color: var(--pm-gray-light-2); }
+
+.generic .odd .alphaChar{ background-color: var(--pm-gray-light-2); }
+.generic .even .alphaChar{ background-color:  var(--pm-gray-light-1); }
+
+table tr.odd { background-color:  var(--pm-gray-light-2); }
+table tr.even { background-color:  var(--pm-gray-light-1); }
+
+table, pre {
+  background-color: var(--pm-gray-light-1);
+  color: var(--pm-gray-dark);
+}
+
+hr { background-color: var(--pm-gray-medium-1);
+     border: 1px solid var(--pm-pflaster-dark);
+}
+th {
+    background-color: var(--pm-gray-medium-2);
+    border-left: 1px solid var(--pm-gray-dark);
+}
+
+/* Margins, padding etc */
+.content ul li { padding-left: 0.5em }
+.content ul { padding-left: 2.0em; }
+.content h2 {
+    margin-top: 1.5em;
+    margin-bottom: 0.5em;
+}

doc/qdoc/qmlplugin.qdocconf

@@ -6,7 +6,8 @@ url             = https://github.com/sailfishos-patches/patchmanager
 
 include(common.qdocconf)
 
-depends += qtcore qtqml
+depends += qtcore qtqml qtnetwork qtdbus qtgui
+depends += patchmanager daemon
 
 headerdirs = ../../src/qml
 #headers.fileextensions = "*.h *.hpp"
@@ -15,5 +16,5 @@ sourcedirs = ../../src/qml
 sources += qmlplugin.qdoc
 #sources.fileextensions = "*.cpp *.qdoc *.qml"
 
-# get rid of warnings about undoicumented stuff in patchmanager.h
+# try to get rid of warnings about undocumented stuff in patchmanager.h
 Cpp.ignoretokens += Q_PROPERTY

makedocs

@@ -52,12 +52,16 @@ if [ -z "$QT_INSTALL_DOCS" ]; then
 		QT_INSTALL_DOCS=/usr/share/doc/qt5
 	elif [ -f /usr/share/qt5/doc/global/macros.qdocconf ]; then
 		QT_INSTALL_DOCS=/usr/share/qt5/doc
+	else
+		printf '## ERROR: global macro config does not exist.\n'
+		printf "## You probably need to install \'qt5-tools\''\n"
+		exit 1
 	fi
 fi
 
 printf '## Generating Docs...\n'
 [ -d $OUT ] && rm -r $OUT
-qdoc --no-examples --outputdir $OUT --outputformat HTML --installdir $QMAKE_INSTALL_ROOT/doc doc/qdoc/master.qdocconf --single-exec $@
+qdoc --no-examples --showinternal --outputdir $OUT --outputformat HTML --installdir $QMAKE_INSTALL_ROOT/doc doc/qdoc/master.qdocconf --single-exec $@
 printf '## End of Doc generation at "%s"\n' "$OUT"
 
 [ $switched_dirs = "true" ] && popd >/dev/null || cd -

src/bin/dialog/dialog.qdoc

@@ -1,6 +1,6 @@
 /*!
   \title Patchmanager Documentation: Startup Dialog
-  \page index.html overview
+  \page index.html
   \indexpage Patchmanager Documentation
 
   This is a very simple Sailfish OS application that upon start checks the state of the Patchmanager Daemon to see whether it needs to launch a GUI.

src/bin/patchmanager-daemon/daemon.qdoc

@@ -9,7 +9,7 @@
     A D-Bus activated background service which manages patch un/installation,
     listing, de/actvation, and communication with the preload library.
 
-    Patchmanager is usually launched by its DBus service.
+    Patchmanager is usually launched by its D-Bus service.
 
     If the \c patchmanager binary is called from command line, it
     can also serve as a simple CLI to a running daemon.

src/bin/patchmanager-daemon/inotifywatcher.cpp

@@ -73,14 +73,15 @@ INotifyWatcher::INotifyWatcher(QObject *parent)
     \inmodule PatchManagerDaemon
     \inherits QSocketNotifier
     \brief watches a list of files or directories for changes
+    \internal
 */
 /*! \fn void INotifyWatcher::directoryChanged(const QString &path, bool removed);
     \fn void INotifyWatcher::fileChanged(const QString &path, bool removed);
     This signal is emitted when a file or directory has changed.
     Parameters are the \a path and whether it was \a removed.
  */
 /*! \fn void INotifyWatcher::contentChanged(const QString &path, bool created);
-    This signal is emitted when directory content has changed
+    This signal is emitted when directory content has changed.
     Parameters are the \a path and whether something was \a created.
  */
 INotifyWatcher::~INotifyWatcher()
@@ -92,7 +93,7 @@ INotifyWatcher::~INotifyWatcher()
     ::close(inotifyFd);
 }
 
-/*! Add \a paths to the list of paths to be watched. */
+/*! This function adds \a paths to the list of paths to be watched and returns the new list. */
 QStringList INotifyWatcher::addPaths(const QStringList &paths)
 {
     QStringList p = paths;
@@ -142,7 +143,7 @@ QStringList INotifyWatcher::addPaths(const QStringList &paths)
     return p;
 }
 
-/*! Removes \a paths from the list of paths to be watched. */
+/*! This function removes \a paths from the list of paths to be watched and returns the new path list.  */
 QStringList INotifyWatcher::removePaths(const QStringList &paths)
 {
     QStringList p = paths;

src/bin/patchmanager-daemon/journal.cpp

@@ -6,9 +6,17 @@
 
 /*! \class Journal
     \inmodule PatchManagerDaemon
+    \brief Interface to the systemd Journal.
+    \internal
+
+    Listens on the systemd Journal for certain messages.
+
+    This is done to be able to detect when Lipstick throws an error on start,
+    and a file from a patch caused an error.
+
 */
 /*! \fn Journal::matchFound()
-   Emitted when the fileters found a log entry that matched.
+   Emitted when the filters found a log entry that matched.
 */
 Journal::Journal(QObject *parent)
     : QObject(parent)
@@ -45,7 +53,7 @@ void Journal::wait()
     thread->start();
 }
 
-/*! Attaches itself to the Journal, filetering for \e Lipstick and \e jolla-settings executables. */
+/*! Attaches itself to the Journal, filtering for \e Lipstick and \e jolla-settings executables. */
 void Journal::init()
 {
     qDebug() << Q_FUNC_INFO;
@@ -67,7 +75,7 @@ void Journal::init()
     wait();
 }
 
-/*! Read the message from the Journal, look got certain strings, and emit the matchFound signal if found.
+/*! Read the messages, look for certain strings, and emit the matchFound signal if found.
 
   Strings looked for are: