Skip to content

Commit 5c34e1a

Browse files
andyholmesandyholmes
committed
docs: add user documentation
* add yelp scaffolding * add validation test * add build test to CI * add HTML generation to CD * update RPM spec
1 parent 659d48d commit 5c34e1a

32 files changed

+1574
-30
lines changed

‎.editorconfig‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,7 @@ max_line_length = 80
2727
indent_size = 4
2828
indent_style = space
2929

30-
[*.{css,ui,xml,xml.in,yml}]
30+
[*.{css,page,ui,xml,xml.in,yml}]
3131
indent_size = 2
3232
indent_style = space
3333

‎.github/workflows/cd.yml‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,7 @@ jobs:
2626
suite: test
2727
setup-args: |
2828
-Ddocumentation=true
29+
-Dhelp=true
2930
-Dtests=true
3031
test-coverage: true
3132
lcov-include: '${{ github.workspace }}/src/*'
@@ -54,6 +55,23 @@ jobs:
5455
target-folder: documentation
5556
single-commit: true
5657

58+
- name: Build (help)
59+
env:
60+
WORKSPACE: ${{ github.workspace }}
61+
run: |
62+
mkdir -p _help
63+
yelp-build html -o _help \
64+
-x ${WORKSPACE}/help/valent-html.xsl \
65+
${WORKSPACE}/help/C/
66+
67+
- name: Help
68+
continue-on-error: true
69+
uses: JamesIves/github-pages-deploy-action@releases/v4
70+
with:
71+
folder: _help
72+
target-folder: help
73+
single-commit: true
74+
5775
flatpak:
5876
name: Flatpak
5977
runs-on: ubuntu-latest

‎.github/workflows/ci.yml‎

Lines changed: 30 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -81,33 +81,6 @@ jobs:
8181
reporter: github-pr-review
8282
fail_on_error: true
8383

84-
build:
85-
name: Build (Documentation)
86-
needs: [pre-test]
87-
runs-on: ubuntu-latest
88-
container:
89-
image: ghcr.io/${{ github.repository }}:${{ github.base_ref }}
90-
91-
steps:
92-
- name: Checkout
93-
uses: actions/checkout@v3
94-
with:
95-
submodules: true
96-
97-
- name: Build
98-
run: |
99-
meson setup --buildtype=release \
100-
-Ddocumentation=true \
101-
_build
102-
meson compile -C _build
103-
104-
- name: Upload
105-
if: ${{ failure() }}
106-
uses: actions/upload-artifact@v3
107-
with:
108-
name: Documentation
109-
path: _build/doc/sdk/valent
110-
11184
analyze:
11285
name: Static Analysis
11386
needs: [pre-test]
@@ -154,6 +127,36 @@ jobs:
154127
name: Static Analysis (${{ matrix.suite }})
155128
path: _build/meson-logs
156129

130+
build:
131+
name: Tests (Build)
132+
needs: [pre-test]
133+
runs-on: ubuntu-latest
134+
container:
135+
image: ghcr.io/${{ github.repository }}:${{ github.base_ref }}
136+
137+
steps:
138+
- name: Checkout
139+
uses: actions/checkout@v3
140+
with:
141+
submodules: true
142+
143+
- name: Build
144+
run: |
145+
meson setup --buildtype=release \
146+
--prefix=/usr \
147+
-Ddocumentation=true \
148+
-Dhelp=true \
149+
_build
150+
meson compile -C _build
151+
meson install -C _build
152+
153+
- name: Test Report
154+
if: ${{ failure() }}
155+
uses: actions/upload-artifact@v3
156+
with:
157+
name: Tests (Build)
158+
path: _build/meson-logs
159+
157160
test:
158161
name: Tests
159162
needs: [pre-test]

‎.reuse/dep5‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,3 +9,7 @@ Files: .github .gitignore .gitmodules build-aux/* CHANGELOG.md CONTRIBUTING.md
99
Copyright: No rights reserved
1010
License: CC0-1.0
1111

12+
Files: help/*.page help/*.tmpl help/*/legal.xml
13+
Copyright: 2022 Andy Holmes <andrew.g.r.holmes@gmail.com>
14+
License: CC-BY-SA-4.0
15+

‎LICENSES/CC-BY-SA-4.0.txt‎

Lines changed: 170 additions & 0 deletions
Large diffs are not rendered by default.

‎build-aux/contrib/valent.spec‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,9 @@ Source0: %{url}/archive/v%{version}/%{name}-%{tarball_version}.tar.gz
2121
BuildRequires: firewalld-filesystem
2222
BuildRequires: gcc
2323
BuildRequires: gettext
24+
BuildRequires: itstool
2425
BuildRequires: meson
26+
BuildRequires: yelp-tools
2527
BuildRequires: pkgconfig(gio-2.0) %{glib2_version}
2628
BuildRequires: pkgconfig(gio-unix-2.0) %{glib2_version}
2729
BuildRequires: pkgconfig(gnutls)
@@ -74,12 +76,12 @@ The %{name}-tests package contains precompiled unit tests for %{name}
7476
%autosetup -p1 -n %{name}-%{tarball_version}
7577

7678
%build
77-
%meson --buildtype=release -Ddocumentation=true -Dfirewalld=true -Dtests=true -Dfuzz_tests=false
79+
%meson --buildtype=release -Ddocumentation=true -Dfirewalld=true -Dhelp=true -Dtests=true -Dfuzz_tests=false
7880
%meson_build
7981

8082
%install
8183
%meson_install
82-
%find_lang %{name}
84+
%find_lang %{name} --with-gnome
8385

8486
%check
8587
appstream-util validate-relax --nonet %{buildroot}%{_metainfodir}/*.xml

‎help/C/device-setup.page‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
<page xmlns="http://projectmallard.org/1.0/" version="1.1"
2+
xmlns:its="http://www.w3.org/2005/11/its"
3+
type="topic" style="task"
4+
id="device-setup">
5+
6+
<info>
7+
<include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude"/>
8+
<credit type="author">
9+
<name>Andy Holmes</name>
10+
<email>andrew.g.r.holmes@gmail.com</email>
11+
<years>2023</years>
12+
</credit>
13+
14+
<link type="guide" xref="index#getting-started"/>
15+
<link type="seealso" href="https://userbase.kde.org/KDEConnect#Pairing_two_devices_together">
16+
<title>KDE Connect — Pairing two devices together</title>
17+
</link>
18+
19+
<title type="text">Setup a new device</title>
20+
<desc>Connect and configure a new device</desc>
21+
</info>
22+
23+
<title>Setup a new device</title>
24+
25+
<p>
26+
Before starting, ensure that both devices you want to connect are on the
27+
same local network.
28+
</p>
29+
30+
<steps>
31+
<item>
32+
<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>
33+
<p><media its:translate="no" type="image" src="media/screenshots/main-window-refresh.png"/></p>
34+
</item>
35+
<item>
36+
<p>Wait for the device to appear in the device list.</p>
37+
<p><media its:translate="no" type="image" src="media/screenshots/main-window-unpaired.png"/></p>
38+
</item>
39+
</steps>
40+
41+
<note style="tip">
42+
<p>
43+
Information about connecting official <app>KDE Connect</app> clients can
44+
be found on the
45+
<link href="https://userbase.kde.org/KDEConnect">KDE Connect Wiki</link>.
46+
</p>
47+
</note>
48+
</page>

‎help/C/index.page‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
<page xmlns="http://projectmallard.org/1.0/" version="1.1"
2+
xmlns:its="http://www.w3.org/2005/11/its"
3+
type="guide"
4+
id="index">
5+
<info>
6+
<include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude"/>
7+
<credit type="author">
8+
<name>Andy Holmes</name>
9+
<email>andrew.g.r.holmes@gmail.com</email>
10+
<years>2023</years>
11+
</credit>
12+
13+
<!-- Override the page title which includes a full-color icon -->
14+
<title type="link" role="guide">Valent</title>
15+
<title type="link" role="trail">Valent</title>
16+
17+
<title type="text">Valent</title>
18+
<desc>Connect, control and sync devices</desc>
19+
</info>
20+
21+
<title>
22+
<media type="image" width="48px" height="48px" its:translate="no"
23+
src="media/ca.andyholmes.Valent.svg" /> Valent Help
24+
</title>
25+
26+
<section id="getting-started" style="2column">
27+
<title>Getting Started</title>
28+
</section>
29+
30+
<section id="preferences" style="2column">
31+
<title>Preferences</title>
32+
</section>
33+
34+
<section id="troubleshooting" style="2column">
35+
<title>Troubleshooting</title>
36+
</section>
37+
</page>
38+

‎help/C/introduction.page‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
<page xmlns="http://projectmallard.org/1.0/" version="1.1"
2+
type="topic"
3+
id="introduction">
4+
5+
<info>
6+
<include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude"/>
7+
<credit type="author">
8+
<name>Andy Holmes</name>
9+
<email>andrew.g.r.holmes@gmail.com</email>
10+
<years>2023</years>
11+
</credit>
12+
13+
<link type="guide" xref="index"/>
14+
<link type="seealso" href="https://kdeconnect.kde.org">
15+
<title>KDE Connect Homepage</title>
16+
</link>
17+
18+
<title type="text">Introduction</title>
19+
<desc>Learn about Valent</desc>
20+
</info>
21+
22+
<title>Introduction</title>
23+
24+
<p>
25+
<app>Valent</app> is an application for securely connecting devices, most
26+
commonly mobile phones and desktop computers.
27+
</p>
28+
<p>
29+
Devices can control media players, sync notifications and contacts, share
30+
files and links, control the mouse and keyboard remotely and more.
31+
</p>
32+
<p>
33+
<app>Valent</app> is an implementation of the <app>KDE Connect</app>
34+
protocol and can connect to any other conforming implementation. The KDE
35+
Connect project has clients for Linux, Android, SailfishOS, macOs, Windows
36+
and more.
37+
</p>
38+
</page>

‎help/C/legal.xml‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
<license xmlns="http://projectmallard.org/1.0/"
2+
href="http://creativecommons.org/licenses/by-sa/4.0/">
3+
<p>This work is licensed under a
4+
<link href="http://creativecommons.org/licenses/by-sa/4.0/">Creative Commons
5+
Attribution-ShareAlike 4.0 International</link> license.</p>
6+
</license>

0 commit comments

Comments
 (0)