Switch library documentation to gi-docgen
Switch from gtk-doc to gi-docgen for the library documentation and adjust the source files accordingly. We don't bother about the daemon doc headers as they're not built into any docs atm. Closes: #56
This commit is contained in:
Guido Günther
@@ -0,0 +1,57 @@
|
||||
Title: Compiling with libfeedback
|
||||
Slug: building
|
||||
|
||||
# Compiling with libfeedback
|
||||
|
||||
If you need to build libfeedback, get the source from
|
||||
[here](https://source.puri.sm/Librem5/feedbackd) and see the `README.md` file.
|
||||
|
||||
## Using `pkg-config`
|
||||
|
||||
Like other GObject based libraries, libfeedback uses `pkg-config` to provide compiler
|
||||
options. The package name is `libfeedback-0.0`.
|
||||
|
||||
When using the Meson build system you can declare a dependency like:
|
||||
|
||||
```meson
|
||||
dependency('libfeedback-0.0')
|
||||
```
|
||||
|
||||
## Bundling the Library
|
||||
|
||||
### Using a Subproject
|
||||
|
||||
Libfeedback can be used as a Meson subproject. Create a
|
||||
`subprojects/libfeedback.wrap` file with the following contents:
|
||||
|
||||
```ini
|
||||
[wrap-git]
|
||||
directory=libfeedback
|
||||
url=https://source.puri.sm/Librem5/feedbackd.git
|
||||
revision=main
|
||||
depth=1
|
||||
```
|
||||
|
||||
Add this to your `meson.build`:
|
||||
|
||||
```meson
|
||||
libfeedback = dependency(
|
||||
'libfeedback-0.0',
|
||||
version: '>= 0.0.1',
|
||||
fallback: ['libfeedback', 'libfeedback_dep'],
|
||||
default_options: [
|
||||
'daemon=false',
|
||||
'man=false',
|
||||
'gtk_doc=false',
|
||||
'vapi=false',
|
||||
'tests=false',
|
||||
]
|
||||
)
|
||||
```
|
||||
|
||||
Then the `libfeedback` variable can be used as a dependency.
|
||||
|
||||
# Next Steps
|
||||
|
||||
Once libfeedback has been compiled and included into your project, it needs to be
|
||||
initialized. See [Initialization](initialization.html).
|
||||
@@ -0,0 +1,34 @@
|
||||
Title: Initialization
|
||||
Slug: initialization
|
||||
|
||||
# Initialization
|
||||
|
||||
Before using libfeedback, it must be initialized. To use the library
|
||||
call [func@Lfb.init]() with the id of your application (usually
|
||||
the desktop file name without the .desktop extension). For that you
|
||||
include the `libfeedback.h` header. Since the API is considered
|
||||
unstable at this point in time you need to acknowledge this by
|
||||
definining `LIBFEEDBACK_USE_UNSTABLE_API`:
|
||||
|
||||
```c
|
||||
#define LIBFEEDBACK_USE_UNSTABLE_API
|
||||
#include <libfeedback.h>
|
||||
|
||||
int main(void)
|
||||
{
|
||||
g_autoptr (GError) *err = NULL;
|
||||
if (lfb_init ("com.example.appid", &err)) {
|
||||
g_error ("%s", err->message);
|
||||
}
|
||||
...
|
||||
lfb_uninit ();
|
||||
return 0;
|
||||
}
|
||||
```
|
||||
|
||||
You can also acknowledge this with the definition option of your C
|
||||
compiler, like `-DFEEDBACK_USE_UNSTABLE_API`.
|
||||
|
||||
After initializing the library you can trigger feedback using
|
||||
[class@Lfb.Event] objects. When your application finishes call
|
||||
[func@Lfb.uninit]() to free any resources:
|
||||
@@ -1,68 +0,0 @@
|
||||
<?xml version="1.0"?>
|
||||
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
|
||||
"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"
|
||||
[
|
||||
<!ENTITY % local.common.attrib "xmlns:xi CDATA #FIXED 'http://www.w3.org/2003/XInclude'">
|
||||
<!ENTITY % gtkdocentities SYSTEM "xml/gtkdocentities.ent">
|
||||
%gtkdocentities;
|
||||
]>
|
||||
<book id="index">
|
||||
<bookinfo>
|
||||
<title>&package_name; Reference Manual</title>
|
||||
<releaseinfo>
|
||||
<para>This document is the API reference for &package_name; &package_version;</para>
|
||||
<para>
|
||||
<ulink type="http" url="&package_url;">Libfeedback</ulink> is a library to trigger
|
||||
feedback (such as haptic feedback) via events sent by your application.
|
||||
</para>
|
||||
<para>
|
||||
If you find any issues in this API reference, please report it using
|
||||
<ulink type="http" url="&package_bugreport;">the bugtracker</ulink>.
|
||||
</para>
|
||||
</releaseinfo>
|
||||
|
||||
<copyright>
|
||||
<year>2020</year>
|
||||
<holder>Purism SPC</holder>
|
||||
</copyright>
|
||||
</bookinfo>
|
||||
|
||||
<xi:include href="overview.xml"/>
|
||||
|
||||
<part>
|
||||
<title>API Reference</title>
|
||||
|
||||
<chapter id="core-api">
|
||||
<title>Core API</title>
|
||||
<xi:include href="xml/libfeedback.xml"/>
|
||||
<xi:include href="xml/lfb-event.xml"/>
|
||||
</chapter>
|
||||
|
||||
<chapter id="low-level-api">
|
||||
<title>Low level api</title>
|
||||
<xi:include href="xml/lfb-gdbus.xml"/>
|
||||
<xi:include href="xml/lfb-names.xml"/>
|
||||
</chapter>
|
||||
|
||||
<chapter id="dbus-interface">
|
||||
<title>DBus Interface</title>
|
||||
<xi:include href="../data/libfeedback-org.sigxcpu.Feedback.xml"/>
|
||||
</chapter>
|
||||
</part>
|
||||
|
||||
<chapter id="object-tree">
|
||||
<title>Object Hierarchy</title>
|
||||
<xi:include href="xml/tree_index.sgml"/>
|
||||
</chapter>
|
||||
|
||||
<index id="api-index-full">
|
||||
<title>API Index</title>
|
||||
<xi:include href="xml/api-index-full.xml"><xi:fallback /></xi:include>
|
||||
</index>
|
||||
|
||||
<index id="annotations-glossary">
|
||||
<title>Annotations glossary</title>
|
||||
<xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>
|
||||
</index>
|
||||
|
||||
</book>
|
||||
@@ -0,0 +1,42 @@
|
||||
[library]
|
||||
version = "@VERSION@"
|
||||
description = "A library to trigger feedback (such as haptic feedback) via events sent by your application."
|
||||
authors = "Purism SPC"
|
||||
license = "LGPL-2.1-or-later"
|
||||
browse_url = "https://source.puri.sm/Librem5/feedbackd/"
|
||||
repository_url = "https://source.puri.sm/Librem5/feedbackd.git"
|
||||
website_url = "https://source.puri.sm/Librem5/feedbackd/"
|
||||
dependencies = [
|
||||
"Gio-2.0",
|
||||
"GLib-2.0",
|
||||
]
|
||||
devhelp = true
|
||||
search_index = true
|
||||
|
||||
[dependencies."Gio-2.0"]
|
||||
name = "GIO"
|
||||
description = "GObject Interfaces and Objects, Networking, IPC, and I/O"
|
||||
docs_url = "https://docs.gtk.org/gio/"
|
||||
|
||||
[dependencies."GLib-2.0"]
|
||||
name = "GLib "
|
||||
description = "The base type system library"
|
||||
docs_url = "https://docs.gtk.org/glib/"
|
||||
|
||||
[theme]
|
||||
name = "basic"
|
||||
show_index_summary = true
|
||||
show_class_hierarchy = true
|
||||
|
||||
[source-location]
|
||||
# The base URL for the web UI
|
||||
base_url = "https://source.puri.sm/Librem5/feedbackd/-/blob/main/"
|
||||
# The format for links, using "filename" and "line" for the format
|
||||
file_format = "{filename}#L{line}"
|
||||
|
||||
[extra]
|
||||
content_files = [
|
||||
"overview.md",
|
||||
"build-howto.md",
|
||||
"initialization.md",
|
||||
]
|
||||
+40
-32
@@ -1,41 +1,49 @@
|
||||
if get_option('gtk_doc')
|
||||
|
||||
subdir('xml')
|
||||
|
||||
private_headers = [
|
||||
expand_content_md_files = [
|
||||
'overview.md',
|
||||
'build-howto.md',
|
||||
'initialization.md',
|
||||
]
|
||||
|
||||
content_files = [
|
||||
'overview.xml',
|
||||
]
|
||||
toml_data = configuration_data()
|
||||
toml_data.set('VERSION', meson.project_version())
|
||||
|
||||
glib_prefix = dependency('glib-2.0').get_pkgconfig_variable('prefix')
|
||||
glib_docpath = join_paths(glib_prefix, 'share', 'gtk-doc', 'html')
|
||||
docpath = join_paths(get_option('datadir'), 'gtk-doc', 'html')
|
||||
libfeedback_toml = configure_file(
|
||||
input: 'libfeedback.toml.in',
|
||||
output: 'libfeedback.toml',
|
||||
configuration: toml_data
|
||||
)
|
||||
|
||||
dependency('gi-docgen', version: '>= 2021.1',
|
||||
fallback: ['gi-docgen', 'dummy_dep'],
|
||||
native: true,
|
||||
required: get_option('gtk_doc'))
|
||||
|
||||
gidocgen = find_program('gi-docgen')
|
||||
|
||||
docs_dir = datadir / 'doc'
|
||||
|
||||
custom_target('libfeedback-doc',
|
||||
input: [ libfeedback_toml, libfeedback_gir[0] ],
|
||||
output: 'libfeedback-0',
|
||||
command: [
|
||||
gidocgen,
|
||||
'generate',
|
||||
'--quiet',
|
||||
'--add-include-path=@0@'.format(meson.current_build_dir() / '../src'),
|
||||
'--config=@INPUT0@',
|
||||
'--output-dir=@OUTPUT@',
|
||||
'--no-namespace-dir',
|
||||
'--content-dir=@0@'.format(meson.current_source_dir()),
|
||||
'@INPUT1@',
|
||||
],
|
||||
depend_files: [ expand_content_md_files ],
|
||||
build_by_default: true,
|
||||
install: true,
|
||||
install_dir: docs_dir,
|
||||
)
|
||||
|
||||
gnome.gtkdoc('libfeedback',
|
||||
main_xml: 'libfeedback-docs.xml',
|
||||
src_dir: [
|
||||
join_paths(meson.source_root(), 'libfeedback'),
|
||||
join_paths(meson.build_root(), 'libfeedback'),
|
||||
join_paths(meson.build_root(), 'data'),
|
||||
],
|
||||
dependencies: libfeedback_dep,
|
||||
gobject_typesfile: 'libfeedback.types',
|
||||
scan_args: [
|
||||
'--rebuild-types',
|
||||
'--ignore-headers=' + ' '.join(private_headers),
|
||||
],
|
||||
fixxref_args: [
|
||||
'--html-dir=@0@'.format(docpath),
|
||||
'--extra-dir=@0@'.format(join_paths(glib_docpath, 'glib')),
|
||||
'--extra-dir=@0@'.format(join_paths(glib_docpath, 'gobject')),
|
||||
'--extra-dir=@0@'.format(join_paths(glib_docpath, 'gio')),
|
||||
'--extra-dir=@0@'.format(join_paths(glib_docpath, 'gi')),
|
||||
],
|
||||
install_dir: 'libfeedback',
|
||||
content_files: content_files,
|
||||
install: true)
|
||||
endif
|
||||
|
||||
if get_option('man')
|
||||
|
||||
@@ -0,0 +1,23 @@
|
||||
Title: Overview
|
||||
Slug: Overview
|
||||
|
||||
# Libfeedback Introduction
|
||||
|
||||
The purpose of libfeedback is to make it simple to supply audible,
|
||||
haptic and visual feedback to the user. This is done by
|
||||
notifying a feedback_daemon over DBus that a certain event
|
||||
happened. The daemon then selects the appropriate feedbacks (such
|
||||
as a buzzing haptic motor or playing an audio file) based on the
|
||||
user session's current feedback profile, feedback theme and
|
||||
available hardware.
|
||||
|
||||
Events are identified by strings like `message-new-sms` or
|
||||
`message-new-sms`. The available event names are described in the
|
||||
[Event naming specification](Event-naming-spec-0.0.0.html).
|
||||
|
||||
Libfeedback provides synchronous and asynchronous APIs to trigger and
|
||||
stop feedback for these events and is usable from other languages than
|
||||
C by GObject introspection.
|
||||
|
||||
See [Compiling with libfeedback](build-howto.html) on how to include
|
||||
libfeedback in your project.
|
||||
@@ -1,111 +0,0 @@
|
||||
<?xml version="1.0"?>
|
||||
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
|
||||
"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
|
||||
<!ENTITY % local.common.attrib "xmlns:xi CDATA #FIXED 'http://www.w3.org/2003/XInclude'">
|
||||
<!ENTITY % gtkdocentities SYSTEM "xml/gtkdocentities.ent">
|
||||
%gtkdocentities;
|
||||
]>
|
||||
|
||||
<part>
|
||||
<title>Libfeedback Overview</title>
|
||||
|
||||
<chapter>
|
||||
<title>Introduction</title>
|
||||
|
||||
<para>
|
||||
The purpose of libfeedback is to make it simple to supply
|
||||
audible, haptic and visual feedback to the user. This is done
|
||||
by notifying a &feedback_daemon; over DBus that a certain event
|
||||
happened and the daemon selects the appropriate feedbacks (such as
|
||||
a buzzing haptic motor or playing an audio file) based
|
||||
on the user session's current feedback profile, feedback theme and available
|
||||
hardware. Events are identified by strings like
|
||||
<literal>message-new-sms</literal> or
|
||||
<literal>message-new-sms</literal>. The available event names are
|
||||
described in the &event_naming_spec;.
|
||||
</para>
|
||||
<para>
|
||||
&package; provides synchronous and asynchronous APIs to trigger
|
||||
and stop feedback for these events and is usable from other languages
|
||||
than C by GObject introspection.
|
||||
</para>
|
||||
</chapter>
|
||||
|
||||
<chapter>
|
||||
<title>Compiling libfeedback applications</title>
|
||||
<simplesect>
|
||||
<title>Using pkg-config</title>
|
||||
|
||||
<para> Like other GNOME libraries,
|
||||
<application>&package_string;</application> uses
|
||||
<application>pkg-config</application> to provide compiler options. The
|
||||
package name is
|
||||
"<literal>&package_ver_str;</literal>". So in
|
||||
your <literal>configure.ac</literal> script, you might specify something
|
||||
like: </para>
|
||||
|
||||
<informalexample><programlisting>
|
||||
PKG_CHECK_MODULES(LIBFEEDBACK, [&package_string;-&package_api_version;])
|
||||
AC_SUBST(LIBFEEDBACK_CFLAGS)
|
||||
AC_SUBST(LIBFEEDBACK_LIBS)
|
||||
</programlisting></informalexample>
|
||||
</simplesect>
|
||||
|
||||
<simplesect>
|
||||
<title>Using Meson/Ninja</title>
|
||||
<para>
|
||||
If using Meson/Ninja use a <literal>dependency('&package_string;-&package_api_version;')
|
||||
</literal> dependency.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The "<literal>&package_api_version;</literal>" in the package name is the "API version"
|
||||
(indicating "the version of the <application>&package_string;</application> API
|
||||
that first appeared in version &package_api_version;") and is essentially just part of
|
||||
the package name.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
When using the Meson build system you can declare a dependency like
|
||||
</para>
|
||||
<informalexample><programlisting>
|
||||
dependency(libfeedback-0.0')
|
||||
</programlisting></informalexample>
|
||||
|
||||
</simplesect>
|
||||
|
||||
<simplesect>
|
||||
<title>Acknowledge the Instability</title>
|
||||
|
||||
<para>
|
||||
Since the library is young and is still changing a lot, in order to use it you are required to acknowledge that your are using an unstable API.
|
||||
To do so, <literal>LIBFEEDBACK_USE_UNSTABLE_API</literal> must be defined for compilation to succeed.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
From C code or any compatible language, you can prefix your inclusion of the &package_string; header like so:
|
||||
</para>
|
||||
|
||||
<informalexample><programlisting>
|
||||
#define LIBFEEDBACK_USE_UNSTABLE_API
|
||||
#include <libfeedback.h>
|
||||
</programlisting></informalexample>
|
||||
|
||||
<para>
|
||||
Including individual headers rather than <literal>libfeedback.h</literal> is not
|
||||
recommended.
|
||||
</para>
|
||||
<para>
|
||||
You can also acknowledge this with the definition option of your C compiler, like <literal>-DFEEDBACK_USE_UNSTABLE_API</literal>.
|
||||
This is required from Vala.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
To use &package_name; from Vala, you must define the acknowledgment in C via <literal>-X -DFEEDBACK_USE_UNSTABLE_API</literal>.
|
||||
If your build system uses a two pass compilation and hence your Vala compiler outputs C (Meson, Automake, or using the <literal>--ccode</literal> Vala compiler option trigger that) then you must add <literal>-DLIBFEEDBACK_USE_UNSTABLE_API</literal> to your C compiler arguments instead.
|
||||
</para>
|
||||
</simplesect>
|
||||
|
||||
</chapter>
|
||||
|
||||
</part>
|
||||
@@ -1,11 +0,0 @@
|
||||
<!ENTITY package "@PACKAGE@">
|
||||
<!ENTITY package_bugreport "@PACKAGE_BUGREPORT@">
|
||||
<!ENTITY package_name "@PACKAGE_NAME@">
|
||||
<!ENTITY package_string "@PACKAGE_STRING@">
|
||||
<!ENTITY package_tarname "@PACKAGE_TARNAME@">
|
||||
<!ENTITY package_url "@PACKAGE_URL@">
|
||||
<!ENTITY package_version "@PACKAGE_VERSION@">
|
||||
<!ENTITY package_api_version "@PACKAGE_API_VERSION@">
|
||||
<!ENTITY package_ver_str "@PACKAGE_STRING@-@PACKAGE_API_VERSION@">
|
||||
<!ENTITY event_naming_spec "<ulink url='https://source.puri.sm/Librem5/feedbackd/blob/main/Event-naming-spec-0.0.0.md#standard-event-names'>Event naming specification draft</ulink>">
|
||||
<!ENTITY feedback_daemon "<ulink url='https://source.puri.sm/Librem5/feedbackd/blob/main/README.md'>Feedback Daemon</ulink>">
|
||||
@@ -1,11 +0,0 @@
|
||||
ent_conf = configuration_data()
|
||||
ent_conf.set('PACKAGE', 'libfeedback')
|
||||
ent_conf.set('PACKAGE_BUGREPORT', 'https://source.puri.sm/Librem5/feedbackd/issues')
|
||||
ent_conf.set('PACKAGE_NAME', 'libfeedback')
|
||||
ent_conf.set('PACKAGE_STRING', 'libfeedback')
|
||||
ent_conf.set('PACKAGE_TARNAME', 'libfeedback-' + meson.project_version())
|
||||
ent_conf.set('PACKAGE_URL', 'https://source.puri.sm/Librem5/feedbackd')
|
||||
ent_conf.set('PACKAGE_VERSION', meson.project_version())
|
||||
ent_conf.set('PACKAGE_API_VERSION', apiversion)
|
||||
configure_file(input: 'gtkdocentities.ent.in', output: 'gtkdocentities.ent', configuration: ent_conf)
|
||||
|
||||
Reference in New Issue
Block a user