docs: add user documentation

* add yelp scaffolding
* add validation test
* add build test to CI
* add HTML generation to CD
* update RPM spec

.editorconfig

@@ -27,7 +27,7 @@ max_line_length = 80
 indent_size = 4
 indent_style = space
 
-[*.{css,ui,xml,xml.in,yml}]
+[*.{css,page,ui,xml,xml.in,yml}]
 indent_size = 2
 indent_style = space
 

.github/workflows/cd.yml

@@ -26,6 +26,7 @@ jobs:
           suite: test
           setup-args: |
             -Ddocumentation=true
+            -Dhelp=true
             -Dtests=true
           test-coverage: true
           lcov-include: '${{ github.workspace }}/src/*'
@@ -54,6 +55,23 @@ jobs:
           target-folder: documentation
           single-commit: true
 
+      - name: Build (help)
+        env:
+          WORKSPACE: ${{ github.workspace }}
+        run: |
+          mkdir -p _help
+          yelp-build html -o _help \
+                          -x ${WORKSPACE}/help/valent-html.xsl \
+                          ${WORKSPACE}/help/C/
+
+      - name: Help
+        continue-on-error: true
+        uses: JamesIves/github-pages-deploy-action@releases/v4
+        with:
+          folder: _help
+          target-folder: help
+          single-commit: true
+
   flatpak:
     name: Flatpak
     runs-on: ubuntu-latest

.github/workflows/ci.yml

@@ -81,33 +81,6 @@ jobs:
           reporter: github-pr-review
           fail_on_error: true
 
-  build:
-    name: Build (Documentation)
-    needs: [pre-test]
-    runs-on: ubuntu-latest
-    container:
-      image: ghcr.io/${{ github.repository }}:${{ github.base_ref }}
-
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v3
-        with:
-          submodules: true
-
-      - name: Build
-        run: |
-          meson setup --buildtype=release \
-                      -Ddocumentation=true \
-                      _build
-          meson compile -C _build
-
-      - name: Upload
-        if: ${{ failure() }}
-        uses: actions/upload-artifact@v3
-        with:
-          name: Documentation
-          path: _build/doc/sdk/valent
-
   analyze:
     name: Static Analysis
     needs: [pre-test]
@@ -154,6 +127,36 @@ jobs:
           name: Static Analysis (${{ matrix.suite }})
           path: _build/meson-logs
 
+  build:
+    name: Tests (Build)
+    needs: [pre-test]
+    runs-on: ubuntu-latest
+    container:
+      image: ghcr.io/${{ github.repository }}:${{ github.base_ref }}
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+        with:
+          submodules: true
+
+      - name: Build
+        run: |
+          meson setup --buildtype=release \
+                      --prefix=/usr \
+                      -Ddocumentation=true \
+                      -Dhelp=true \
+                      _build
+          meson compile -C _build
+          meson install -C _build
+
+      - name: Test Report
+        if: ${{ failure() }}
+        uses: actions/upload-artifact@v3
+        with:
+          name: Tests (Build)
+          path: _build/meson-logs
+
   test:
     name: Tests
     needs: [pre-test]

.reuse/dep5

@@ -9,3 +9,7 @@ Files: .github .gitignore .gitmodules build-aux/* CHANGELOG.md CONTRIBUTING.md
 Copyright: No rights reserved
 License: CC0-1.0
 
+Files: help/*.page help/*.tmpl help/*/legal.xml
+Copyright: 2022 Andy Holmes <andrew.g.r.holmes@gmail.com>
+License: CC-BY-SA-4.0
+

build-aux/contrib/valent.spec

@@ -21,7 +21,9 @@ Source0:        %{url}/archive/v%{version}/%{name}-%{tarball_version}.tar.gz
 BuildRequires:  firewalld-filesystem
 BuildRequires:  gcc
 BuildRequires:  gettext
+BuildRequires:  itstool
 BuildRequires:  meson
+BuildRequires:  yelp-tools
 BuildRequires:  pkgconfig(gio-2.0) %{glib2_version}
 BuildRequires:  pkgconfig(gio-unix-2.0) %{glib2_version}
 BuildRequires:  pkgconfig(gnutls)
@@ -74,12 +76,12 @@ The %{name}-tests package contains precompiled unit tests for %{name}
 %autosetup -p1 -n %{name}-%{tarball_version}
 
 %build
-%meson --buildtype=release -Ddocumentation=true -Dfirewalld=true -Dtests=true -Dfuzz_tests=false
+%meson --buildtype=release -Ddocumentation=true -Dfirewalld=true -Dhelp=true -Dtests=true -Dfuzz_tests=false
 %meson_build
 
 %install
 %meson_install
-%find_lang %{name}
+%find_lang %{name} --with-gnome
 
 %check
 appstream-util validate-relax --nonet %{buildroot}%{_metainfodir}/*.xml

help/C/device-setup.page

@@ -0,0 +1,48 @@
+<page xmlns="http://projectmallard.org/1.1/"
+      xmlns:its="http://www.w3.org/2005/11/its"
+      type="topic" style="task"
+      id="device-setup">
+
+  <info>
+    <include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude"/>
+    <credit type="author">
+      <name>Andy Holmes</name>
+      <email>andrew.g.r.holmes@gmail.com</email>
+      <years>2023</years>
+    </credit>
+
+    <link type="guide" xref="index#getting-started"/>
+    <link type="seealso" href="https://userbase.kde.org/KDEConnect#Pairing_two_devices_together">
+      <title>KDE Connect — Pairing two devices together</title>
+    </link>
+
+    <title type="text">Setup a new device</title>
+    <desc>Connect and configure a new device</desc>
+  </info>
+
+  <title>Setup a new device</title>
+
+  <p>
+    Before starting, ensure that both devices you want to connect are on the
+    same local network.
+  </p>
+
+  <steps>
+    <item>
+      <p>Press the <media style="button" its:translate="no" type="image" src="media/view-refresh-symbolic.svg"><span its:translate="yes">Refresh</span></media> button in the main window.</p>
+      <p><media its:translate="no" type="image" src="media/screenshots/main-window-refresh.png"/></p>
+    </item>
+    <item>
+      <p>Wait for the device to appear in the device list.</p>
+      <p><media its:translate="no" type="image" src="media/screenshots/main-window-unpaired.png"/></p>
+    </item>
+  </steps>
+
+  <note style="tip">
+    <p>
+      Information about connecting official <app>KDE Connect</app> clients can
+      be found on the
+      <link href="https://userbase.kde.org/KDEConnect">KDE Connect Wiki</link>.
+    </p>
+  </note>
+</page>

help/C/index.page

@@ -0,0 +1,41 @@
+<!-- SPDX-License-Identifier: CC0-1.0 -->
+<!-- SPDX-FileCopyrightText: Andy Holmes <andrew.g.r.holmes@gmail.com> -->
+
+<page xmlns="http://projectmallard.org/1.1/"
+      xmlns:its="http://www.w3.org/2005/11/its"
+      type="guide"
+      id="index">
+  <info>
+    <include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude"/>
+    <credit type="author">
+      <name>Andy Holmes</name>
+      <email>andrew.g.r.holmes@gmail.com</email>
+      <years>2023</years>
+    </credit>
+
+    <!-- Override the page title which includes a full-color icon -->
+    <title type="link" role="guide">Valent</title>
+    <title type="link" role="trail">Valent</title>
+
+    <title type="text">Valent</title>
+    <desc>Connect, control and sync devices</desc>
+  </info>
+
+  <title>
+      <media type="image" width="48px" height="48px" its:translate="no"
+             src="media/ca.andyholmes.Valent.svg" /> Valent Help
+  </title>
+
+  <section id="getting-started" style="2column">
+    <title>Getting Started</title>
+  </section>
+
+  <section id="preferences" style="2column">
+    <title>Preferences</title>
+  </section>
+
+  <section id="troubleshooting" style="2column">
+    <title>Troubleshooting</title>
+  </section>
+</page>
+

help/C/introduction.page

@@ -0,0 +1,38 @@
+<page xmlns="http://projectmallard.org/1.1/"
+      type="topic"
+      id="introduction">
+
+  <info>
+    <include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude"/>
+    <credit type="author">
+      <name>Andy Holmes</name>
+      <email>andrew.g.r.holmes@gmail.com</email>
+      <years>2023</years>
+    </credit>
+
+    <link type="guide" xref="index"/>
+    <link type="seealso" href="https://kdeconnect.kde.org">
+      <title>KDE Connect Homepage</title>
+    </link>
+
+    <title type="text">Introduction</title>
+    <desc>Learn about Valent</desc>
+  </info>
+
+  <title>Introduction</title>
+
+  <p>
+    <app>Valent</app> is an application for securely connecting devices, most
+    commonly mobile phones and desktop computers.
+  </p>
+  <p>
+    Devices can control media players, sync notifications and contacts, share
+    files and links, control the mouse and keyboard remotely and more.
+  </p>
+  <p>
+    <app>Valent</app> is an implementation of the <app>KDE Connect</app>
+    protocol and can connect to any other conforming implementation. The KDE
+    Connect project has clients for Linux, Android, SailfishOS, macOs, Windows
+    and more.
+  </p>
+</page>

help/C/legal.xml

@@ -0,0 +1,6 @@
+<license xmlns="http://projectmallard.org/1.1/"
+         href="http://creativecommons.org/licenses/by-sa/4.0/">
+  <p>This work is licensed under a
+  <link href="http://creativecommons.org/licenses/by-sa/4.0/">Creative Commons
+  Attribution-ShareAlike 4.0 International</link> license.</p>
+</license>

help/C/plugin-battery.page

@@ -0,0 +1,31 @@
+<page xmlns="http://projectmallard.org/1.1/"
+      type="topic" style="task"
+      id="plugin-battery">
+
+  <info>
+    <include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude"/>
+    <credit type="author">
+      <name>Andy Holmes</name>
+      <email>andrew.g.r.holmes@gmail.com</email>
+      <years>2023</years>
+    </credit>
+
+    <link type="guide" xref="plugins#device"/>
+
+    <title type="text">Battery Plugin</title>
+    <desc>Sync battery statistics</desc>
+  </info>
+
+  <title>Battery Plugin</title>
+  <p>Sync battery statistics</p>
+
+  <list>
+    <title>Features</title>
+    <item>
+      <p>Share local battery level and charging status.</p>
+    </item>
+    <item>
+      <p>View remote battery level and charging status.</p>
+    </item>
+  </list>
+</page>