docs: add user documentation

* add first draft of user documentation * add test suite (`yelp-check`) * add build test to CI * add HTML generation to CD * update RPM spec
andyholmes · Apr 10, 2024 · 0ad40bf · 0ad40bf
1 parent 27eb46b
commit 0ad40bf
Show file tree

Hide file tree

Showing 95 changed files with 5,410 additions and 217 deletions.
diff --git a/.editorconfig b/.editorconfig
@@ -23,7 +23,7 @@ max_line_length = 80
 indent_size = 4
 indent_style = space
 
-[*.{css,toml,ui,xml,xml.in,yml}]
+[*.{css,page,toml,ui,xml,xml.in,yml}]
 indent_size = 2
 indent_style = space
 

diff --git a/.github/workflows/cd.yml b/.github/workflows/cd.yml
@@ -26,11 +26,21 @@ jobs:
           suite: test
           setup-args: |
             -Ddocumentation=true
+            -Dhelp=true
             -Dtests=true
           test-coverage: true
           lcov-include: '${{ github.workspace }}/src/*'
 
-      - name: Report
+      - name: Generate Assets
+        env:
+          WORKSPACE: ${{ github.workspace }}
+        run: |
+          mkdir -p _help
+          yelp-build html -o ${WORKSPACE}/_help \
+                          -x ${WORKSPACE}/help/valent-html.xsl \
+                          ${WORKSPACE}/help/C/
+
+      - name: Coverage (coveralls.io)
         continue-on-error: true
         uses: coverallsapp/github-action@master
         with:
@@ -53,6 +63,14 @@ jobs:
           target-folder: documentation
           single-commit: true
 
+      - 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

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -92,6 +92,7 @@ jobs:
         run: |
           meson setup --buildtype=release \
                       -Ddocumentation=true \
+                      -Dhelp=true \
                       _build
           meson compile -C _build
 
@@ -115,10 +116,12 @@ jobs:
         include:
           - suite: abidiff
             setup-args: |
+              -Dhelp=false
               -Dintrospection=false
               -Dplugins=false
           - suite: cppcheck
             setup-args: |
+              -Dhelp=false
               -Dintrospection=false
               -Dtests=true
       fail-fast: false
@@ -162,19 +165,23 @@ jobs:
         include:
           - suite: test
             setup-args: |
+              -Dhelp=false
               -Dtests=true
             test-args: |
               --repeat=3
           - suite: asan
             setup-args: |
+              -Dhelp=false
               -Dintrospection=false
               -Dtests=true
           - suite: tsan
             setup-args: |
+              -Dhelp=false
               -Dintrospection=false
               -Dtests=true
           - suite: analyzer
             setup-args: |
+              -Dhelp=false
               -Dintrospection=false
               -Dtests=true
       fail-fast: false

diff --git a/.reuse/dep5 b/.reuse/dep5
@@ -9,6 +9,10 @@ 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
+
 Files: src/plugins/findmyphone/data/alert.oga
 Source: https://gitlab.freedesktop.org/xdg/xdg-sound-theme/blob/master/stereo/suspend-error.oga
 Comment: Created by Richard Hughes

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -38,9 +38,13 @@ This project does not yet use a translation service like Weblate or Crowdin. You
 should also expect translatable strings to change frequently until the project
 is more mature.
 
-To contribute a translation, open a pull request which adds your locale to the
-[`LINGUAS`][linguas] file and your translated `.po` file to the [`po/`][po_dir]
-directory.
+To contribute a translation of the application, open a pull request that adds
+your locale to [`po/LINGUAS`][linguas] and your translated `.po` file to
+`po/<locale>.po`.
+
+To contribute a translation of the user help, open a pull request that adds your
+locale to [`help/LINGUAS`][help-linguas] and your translated `.po` file to
+`help/<locale>/<locale>.po`.
 
 
 ## Contributing Code
@@ -121,6 +125,7 @@ already distributed under an acceptable open source license.
 [conventional-commits]: https://www.conventionalcommits.org
 [features]: https://github.com/andyholmes/valent/discussions/new?category=feature-request
 [issues]: https://github.com/andyholmes/valent/issues/new
+[help-linguas]: https://github.com/andyholmes/valent/blob/main/help/LINGUAS
 [linguas]: https://github.com/andyholmes/valent/blob/main/po/LINGUAS
 [po_dir]: https://github.com/andyholmes/valent/tree/main/po
 [gnome-coding-style]: https://developer.gnome.org/documentation/guidelines/programming/coding-style.html

diff --git a/LICENSES/CC-BY-SA-4.0.txt b/LICENSES/CC-BY-SA-4.0.txt
diff --git a/build-aux/contrib/valent.spec b/build-aux/contrib/valent.spec
@@ -20,7 +20,9 @@ Source0:        %{url}/archive/v%{version}/%{name}-%{tarball_version}.tar.gz
 
 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)
@@ -71,12 +73,12 @@ The %{name}-tests package contains precompiled unit tests for %{name}
 %autosetup -p1 -n %{name}-%{tarball_version}
 
 %build
-%meson --buildtype=release -Ddocumentation=true -Dtests=true -Dfuzz_tests=false
+%meson --buildtype=release -Ddocumentation=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

diff --git a/help/C/.yelp-tools.cfg b/help/C/.yelp-tools.cfg
@@ -0,0 +1,54 @@
+# SPDX-License-Identifier: CC-BY-SA-3.0
+# SPDX-FileCopyrightText: GNOME Documentation Project
+# SDPX-FileContributor: Andy Holmes <andrew.g.r.holmes@gmail.com>
+
+[namespaces]
+mal = http://projectmallard.org/1.0/
+xi = http://www.w3.org/2001/XInclude
+
+[check:hrefs]
+allow = https://kdeconnect.kde.org
+
+[check:validate]
+allow = http://www.w3.org/2005/11/its http://itstool.org/extensions/ http://www.w3.org/XML/1998/namespace http://www.w3.org/1999/xlink http://www.w3.org/XML/1998/namespace http://projectmallard.org/experimental/ui/
+
+[check:gnome-info-legal-xi]
+select = /mal:page/mal:info
+assert = xi:include[@href='legal.xml']
+message = Must include legal.xml
+xinclude = false
+
+[check:gnome-info-legal-no]
+select = /mal:page/mal:info
+assert = not(mal:license)
+message = Must not include license directly
+xinclude = false
+
+[check:gnome-desc]
+select = /mal:page/mal:info
+assert = normalize-space(mal:desc) != ''
+message = Must have non-empty desc
+
+[check:gnome-desc-punc]
+select = /mal:page/mal:info/mal:desc
+assert = substring(normalize-space(.), string-length(normalize-space(.))) = '.' or substring(normalize-space(.), string-length(normalize-space(.))) = '?'
+message = Desc must end with a period or question mark
+
+[check:gnome-no-desc-link]
+desc = Stop putting links in desc elements
+select = //mal:desc
+assert = not(mal:link)
+message = Stop putting links in desc elements
+
+[check:gnome-trail-title]
+skip = hardware-auth.page
+desc = Use a short title for link trails
+select = /mal:page[@type='guide']
+assert = string-length(mal:title) <= 20 or (mal:info/mal:title[@type='link' and @role='trail'] and string-length(mal:info/mal:title[@type='link' and @role='trail']) <= 20)
+message = Use a short title for link trails
+
+[check:gnome-no-ascii-quotes]
+select = //mal:*[not(ancestor-or-self::mal:cmd or ancestor-or-self::mal:code or ancestor-or-self::mal:comment or ancestor-or-self::mal:file or ancestor-or-self::mal:input or ancestor-or-self::mal:key or ancestor-or-self::mal:output or ancestor-or-self::mal:screen or ancestor-or-self::mal:screen or ancestor-or-self::mal:sys)]
+assert = not(contains(text(), "'") or contains(text(), '"'))
+message = Use ‘curly’ “quotes” instead of 'straight' "quotes"
+
diff --git a/help/C/device-name.page b/help/C/device-name.page
@@ -0,0 +1,63 @@
+<page xmlns="http://projectmallard.org/1.0/" version="1.1"
+      xmlns:its="http://www.w3.org/2005/11/its"
+      type="topic" style="task"
+      id="device-name">
+
+  <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>
+    </credit>
+
+    <link type="guide" xref="index#getting-started"/>
+
+    <title type="text">Change the device name</title>
+    <desc>How to set the device name.</desc>
+  </info>
+
+  <title>Change the device name</title>
+  <p>
+    The device name is what other devices will see when connecting or pairing
+    with your device. This name will be appear in the device list in the
+    Android app an other <app>KDE Connect</app> clients.
+  </p>
+
+  <steps>
+    <item>
+      <p>
+        Open the main window.
+      </p>
+    </item>
+    <item>
+      <p>
+        Open the
+        <media style="button" its:translate="no" type="image" src="figures/open-menu-symbolic.svg">
+          <gui style="menu" its:translate="yes">Main Menu</gui>
+        </media>
+        menu and select <gui style="menuitem">Preferences</gui>.
+      </p>
+    </item>
+    <item>
+      <p>
+        Select the <gui style="input">Device Name</gui> entry.
+      </p>
+    </item>
+    <item>
+      <p>
+        Choose a new name for the device and press <key>Enter</key> or click the
+        <media style="button" its:translate="no" type="image" src="figures/entry-apply-symbolic.svg">
+          <gui style="button" its:translate="yes">Apply</gui>
+        </media>
+        button.
+      </p>
+    </item>
+  </steps>
+
+  <note style="tip">
+    <p>
+      It may take time for other devices to display the new name.
+    </p>
+  </note>
+</page>
+
diff --git a/help/C/device-pair.page b/help/C/device-pair.page
@@ -0,0 +1,79 @@
+<page xmlns="http://projectmallard.org/1.0/" version="1.1"
+      xmlns:its="http://www.w3.org/2005/11/its"
+      type="topic" style="task"
+      id="device-pair">
+
+  <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>
+    </credit>
+
+    <link type="guide" xref="index#getting-started"/>
+    <link type="seealso" xref="troubleshooting-firewall"/>
+    <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>
+        Open the
+        <gui xref="introduction#main-window">Main Window</gui>
+        and press the
+        <media style="button" its:translate="no" type="image" src="figures/view-refresh-symbolic.svg">
+          <gui style="button" its:translate="yes">Refresh</gui>
+        </media>
+        button.
+      </p>
+    </item>
+    <item>
+      <p>
+        Wait up to 10 seconds for the device to appear in the device list. If
+        your device does not appear, see <link xref="index#troubleshooting"/>
+        for possible solutions.
+      </p>
+    </item>
+    <item>
+      <p>
+        Activate the device row to open the
+        <gui xref="introduction#device-page">Device Page</gui>.
+        You may
+        <link xref="introduction#device-preferences">configure a device</link>
+        before pairing to restrict its access.
+      </p>
+    </item>
+    <item>
+      <p>
+        Activate the <gui style="button">Request Pairing</gui> button, then use
+        the other device to confirm the verification key and accept the request.
+      </p>
+    </item>
+    <item>
+      <p>
+        Once paired, the available actions and information will be revealed on
+        the device page. To unpair the device, open the menu on the device page
+        and select <gui style="menuitem">Unpair</gui>.
+      </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>