Commit cbd4f354 authored by Peter Hutterer's avatar Peter Hutterer
Browse files

dox: switch to sphinx for the user-visible documentation



This is a large commit because it's difficult to split this up and we don't
care about bisecting here anyway.

doxygen is going to produce the API documentation only
sphinx is going to produce the prose user (and a bit of developer) documentation.

The source split is doc/api and doc/user.

Steps performed:
- run the doxygen-to-sphinx.sh script to convert all .dox sources to .rst
- manually fixed the .rst to render correctly
- add a few extra .rst documents to generate the right hierarchy
- hook up sphinx-build in meson
- add a new @mainpage for doxygen more aimed at developers

For the build directory:
- sphinx produces /Documentation
- doxygen now produces /api/

These need to be manually combined in the wayland-web repo, meson doesn't
support subdirectories as output paths within the build dir and the
documentation doesn't need to be installed anywhere.
Signed-off-by: Peter Hutterer's avatarPeter Hutterer <peter.hutterer@who-t.net>
parent 581fbbea
......@@ -13,7 +13,7 @@ INPUT = "@builddir@"
FILTER_PATTERNS = *.h *.dox
IMAGE_PATH = "@builddir@"
GENERATE_HTML = YES
HTML_OUTPUT = Documentation
HTML_OUTPUT = api
SEARCHENGINE = NO
USE_MATHJAX = YES
MATHJAX_RELPATH = https://cdn.mathjax.org/mathjax/latest
......@@ -31,4 +31,3 @@ HTML_FOOTER = "@builddir@/footer.html"
HTML_EXTRA_STYLESHEET = "@builddir@/bootstrap.css" \
"@builddir@/customdoxygen.css" \
"@builddir@/libinputdoxygen.css"
USE_MDFILE_AS_MAINPAGE = "README.md"
/**
@mainpage
This is the libinput API reference.
This documentation is aimed at developers of Wayland compositors. User
documentation is available
[here](https://wayland.freedesktop.org/libinput/doc/latest).
@section concepts Concepts
@subsection concepts_initialization Initialization of a libinput context
libinput provides two different backends:
- a @ref libinput_udev_create_context "udev backend" where notifications
about new and removed devices are provided by udev, and
- a @ref libinput_path_create_context "path backend" where
@ref libinput_path_add_device "device addition" and
@ref libinput_path_remove_device "device removal" need to be handled by
the caller.
See section @ref base for information about initializing a libinput context.
@subsection concepts_events Monitoring for events
libinput exposes a single @ref libinput_get_fd "file descriptor" to the
caller. This file descriptor should be monitored by the caller, whenever
data is available the caller **must** immediately call libinput_dispatch().
Failure to do so will result in erroneous behavior.
libinput_dispatch() may result in one or more events being available to the
caller. After libinput_dispatch() a caller **should** call
libinput_get_event() to retrieve and process this event. Whenever
libinput_get_event() returns `NULL`, no further events are available.
See section @ref event for more information about events.
@subsection concepts_seats Device grouping into seats
All devices are grouped into physical and logical seats. Button and key
states are available per-device and per-seat. See @ref seat for more
information.
@subsection concepts_devices Device capabilities
libinput does not use device types. All devices have @ref
libinput_device_has_capability "capabilities" that define which events may
be generated. See @ref device for more information about devices.
Specific event types include:
- @ref event_keyboard
- @ref event_pointer
- @ref event_touch
- @ref event_gesture
- @ref event_tablet
- @ref event_tablet_pad
- @ref event_switch
@subsection concepts_configuration Device configuration
libinput relies on the caller for device configuration. See
@ref config for more information.
@subsection example An example libinput program
The simplest libinput program looks like this:
@code
static int open_restricted(const char *path, int flags, void *user_data)
{
int fd = open(path, flags);
return fd < 0 ? -errno : fd;
}
static void close_restricted(int fd, void *user_data)
{
close(fd);
}
const static struct libinput_interface interface = {
.open_restricted = open_restricted,
.close_restricted = close_restricted,
};
int main(void) {
struct libinput *li;
struct libinput_event *event;
li = libinput_udev_create_context(&interface, NULL, udev);
libinput_udev_assign_seat(li, "seat0");
libinput_dispatch(li);
while ((event = libinput_get_event(li)) != NULL) {
// handle the event here
libinput_event_destroy(li);
libinput_dispatch(li);
}
libinput_unref(li);
return 0;
}
@endcode
@section building_against Building against libinput
libinput provides a
[pkg-config](https://www.freedesktop.org/wiki/Software/pkg-config/) file.
Software that uses libinput should use pkg-config and the
`PKG_CHECK_MODULES` autoconf macro.
Otherwise, the most rudimentary way to compile and link a program against
libinput is:
@verbatim
gcc -o myprogram myprogram.c `pkg-config --cflags --libs libinput`
@endverbatim
For further information on using pkgconfig see the pkg-config documentation.
@section stability Backwards-compatibility
libinput promises backwards-compatibility across all the 1.x.y version. An
application built against libinput 1.x.y will work with any future 1.*.*
release.
@section About
Documentation generated by from git commit [__GIT_VERSION__](https://gitlab.freedesktop.org/libinput/libinput/commit/__GIT_VERSION__)
*/
......@@ -35,98 +35,26 @@ doc_git_version = vcs_tag(command : ['git', 'log', '-1', '--format=%h'],
output : 'git-version.dox',
replace_string: '__GIT_VERSION__')
readme = vcs_tag(command : ['git', 'log', '-1', '--format=%h'],
mainpage = vcs_tag(command : ['git', 'log', '-1', '--format=%h'],
fallback : 'unknown',
input : '../README.md',
output : 'README.md',
input : 'mainpage.dox',
output : 'mainpage.dox',
replace_string: '__GIT_VERSION__')
src_extra = [
# dot drawings
'dot/seats-sketch.gv',
'dot/seats-sketch-libinput.gv',
'dot/libinput-stack-wayland.gv',
'dot/libinput-stack-xorg.gv',
'dot/libinput-stack-gnome.gv',
'dot/evemu.gv',
# svgs
'svg/button-debouncing-wave-diagram.svg',
'svg/button-scrolling.svg',
'svg/clickfinger.svg',
'svg/clickfinger-distance.svg',
'svg/edge-scrolling.svg',
'svg/gesture-2fg-ambiguity.svg',
'svg/palm-detection.svg',
'svg/pinch-gestures.svg',
'svg/pinch-gestures-softbuttons.svg',
'svg/ptraccel-linear.svg',
'svg/ptraccel-low-dpi.svg',
'svg/ptraccel-touchpad.svg',
'svg/ptraccel-trackpoint.svg',
'svg/software-buttons.svg',
'svg/swipe-gestures.svg',
'svg/tablet-axes.svg',
'svg/tablet-cintiq24hd-modes.svg',
'svg/tablet-interfaces.svg',
'svg/tablet-intuos-modes.svg',
'svg/tablet-left-handed.svg',
'svg/tablet-out-of-bounds.svg',
'svg/tablet.svg',
'svg/tap-n-drag.svg',
'svg/thumb-detection.svg',
'svg/top-software-buttons.svg',
'svg/touchscreen-gestures.svg',
'svg/trackpoint-delta-illustration.svg',
'svg/twofinger-scrolling.svg',
]
src_doxygen = files(
# source files
'../src/libinput.h',
# written docs
'absolute-axes.dox',
'absolute-coordinate-ranges.dox',
'architecture.dox',
'building.dox',
'button_debouncing.dox',
'clickpad-softbuttons.dox',
'contributing.dox',
'device-configuration-via-udev.dox',
'device-quirks.dox',
'faqs.dox',
'gestures.dox',
'middle-button-emulation.dox',
'normalization-of-relative-motion.dox',
'palm-detection.dox',
'page-hierarchy.dox',
'pointer-acceleration.dox',
'reporting-bugs.dox',
'scrolling.dox',
'seats.dox',
'switches.dox',
't440-support.dox',
'tablet-support.dox',
'tapping.dox',
'test-suite.dox',
'timestamps.dox',
'tools.dox',
'touchpad-jumping-cursors.dox',
'touchpad-pressure.dox',
'touchpad-jitter.dox',
'touchpads.dox',
'trackpoints.dox',
'what-is-libinput.dox',
join_paths(meson.source_root(), 'src', 'libinput.h'),
# style files
'style/header.html',
'style/footer.html',
'style/customdoxygen.css',
'style/bootstrap.css',
'style/libinputdoxygen.css',
src_extra,
)
doxyfiles = custom_target('doxyfiles',
input : src_doxygen,
output : '.',
output : 'doxyfiles',
command : [prg_install, '-t', '@OUTDIR@', '@INPUT@'],
build_by_default: true)
......@@ -141,9 +69,9 @@ doxyfile = configure_file(input : 'libinput.doxygen.in',
install : false)
custom_target('doxygen',
input : [ doxyfile, readme, doc_git_version] + src_doxygen + src_extra,
output : [ 'Documentation' ],
input : [ doxyfile, mainpage, doc_git_version] + src_doxygen,
output : [ '.' ],
command : [ doxygen, doxyfile ],
install : false,
depends: [doxyfiles, readme, doc_git_version],
depends: [doxyfiles, mainpage, doc_git_version],
build_by_default : true)
/**
@page Tablets
- @subpage tablet serial numbers
*/
......@@ -252,4 +252,3 @@ blockquote {
margin: 0 24px 0 4px;
padding: 0 12px 0 16px;
}
......@@ -8,7 +8,7 @@
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta name="generator" content="Doxygen $doxygenversion"/>
<script type="text/javascript" src="https://code.jquery.com/jquery-2.1.1.min.js"></script>
<!--BEGIN PROJECT_NAME--><title>$projectname: $title</title><!--END PROJECT_NAME-->
......
/**
@page architecture libinput's internal architecture
This page provides an outline of libinput's internal architecture. The goal
here is to get the high-level picture across and point out the components
and their interplay to new developers.
The public facing API is in `libinput.c`, this file is thus the entry point
for almost all API calls. General device handling is in `evdev.c` with the
device-type-specific implementations in `evdev-<type>.c`. It is not
necessary to understand all of libinput to contribute a patch.
@ref architecture-contexts is the only user-visible implementation detail,
everything else is purely internal implementation and may change when
required.
@section architecture-contexts The udev and path contexts
The first building block is the "context" which can be one of
two types, "path" and "udev". See libinput_path_create_context() and
libinput_udev_create_context(). The path/udev specific bits are in
`path-seat.c` and `udev-seat.c`. This includes the functions that add new
devices to a context.
@dot
digraph context
{
compound=true;
rankdir="LR";
node [
shape="box";
]
libudev [label="libudev 'add' event"]
udev [label="libinput_udev_create_context()"];
udev_backend [label="udev-specific backend"];
context [label="libinput context"]
udev -> udev_backend;
libudev -> udev_backend;
udev_backend -> context;
}
@enddot
The udev context provides automatic device hotplugging as udev's "add"
events are handled directly by libinput. The path context requires that the
caller adds devices.
@dot
digraph context
{
compound=true;
rankdir="LR";
node [
shape="box";
]
path [label="libinput_path_create_context()"];
path_backend [label="path-specific backend"];
xdriver [label="libinput_path_add_device()"]
context [label="libinput context"]
path -> path_backend;
xdriver -> path_backend;
path_backend -> context;
}
@enddot
As a general rule: all Wayland compositors use a udev context, the X.org
stack uses a path context.
Which context was initialized only matters for creating/destroying a context
and adding devices. The device handling itself is the same for both types of
context.
@section architecture-device Device initialization
libinput only supports evdev devices, all the device initialization is done
in `evdev.c`. Much of the libinput public API is also a thin wrapper around
the matching implementation in the evdev device.
There is a 1:1 mapping between libinput devices and `/dev/input/eventX`
device nodes.
@dot
digraph context
{
compound=true;
rankdir="LR";
node [
shape="box";
]
devnode [label="/dev/input/event0"]
libudev [label="libudev 'add' event"]
xdriver [label="libinput_path_add_device()"]
context [label="libinput context"]
evdev [label="evdev_device_create()"]
devnode -> xdriver;
devnode -> libudev;
xdriver -> context;
libudev -> context;
context->evdev;
}
@enddot
Entry point for all devices is `evdev_device_create()`, this function
decides to create a `struct evdev_device` for the given device node.
Based on the udev tags (e.g. `ID_INPUT_TOUCHPAD`), a @ref
architecture-dispatch is initialized. All event handling is then in this
dispatch.
Rejection of devices and the application of quirks is generally handled in
`evdev.c` as well. Common functionality shared across multiple device types
(like button-scrolling) is also handled here.
@section architecture-dispatch Device-type specific event dispatch
Depending on the device type, `evdev_configure_device` creates the matching
`struct evdev_dispatch`. This dispatch interface contains the function
pointers to handle events. Four such dispatch methods are currently
implemented: touchpad, tablet, tablet pad, and the fallback dispatch which
handles mice, keyboards and touchscreens.
@dot
digraph context
{
compound=true;
rankdir="LR";
node [
shape="box";
]
evdev [label="evdev_device_create()"]
fallback [label="evdev-fallback.c"]
touchpad [label="evdev-mt-touchpad.c"]
tablet [label="evdev-tablet.c"]
pad [label="evdev-tablet-pad.c"]
evdev -> fallback;
evdev -> touchpad;
evdev -> tablet;
evdev -> pad;
}
@enddot
While `evdev.c` pulls the event out of libevdev, the actual handling of the
events is performed within the dispatch method.
@dot
digraph context
{
compound=true;
rankdir="LR";
node [
shape="box";
]
evdev [label="evdev_device_dispatch()"]
fallback [label="fallback_interface_process()"];
touchpad [label="tp_interface_process()"]
tablet [label="tablet_process()"]
pad [label="pad_process()"]
evdev -> fallback;
evdev -> touchpad;
evdev -> tablet;
evdev -> pad;
}
@enddot
The dispatch methods then look at the `struct input_event` and proceed to
update the state. Note: the serialized nature of the kernel evdev protocol
requires that the device updates the state with each event but to delay
processing until the `SYN_REPORT` event is received.
@section architecture-configuration Device configuration
All device-specific configuration is handled through `struct
libinput_device_config_FOO` instances. These are set up during device init
and provide the function pointers for the `get`, `set`, `get_default`
triplet of configuration queries (or more, where applicable).
For example, the `struct tablet_dispatch` for tablet devices has a
`struct libinput_device_config_accel`. This struct is set up with the
required function pointers to change the profiles.
@dot
digraph context
{
compound=true;
rankdir="LR";
node [
shape="box";
]
tablet [label="struct tablet_dispatch"]
config [label="struct libinput_device_config_accel"];
tablet_config [label="tablet_accel_config_set_profile()"];
tablet->config;
config->tablet_config;
}
@enddot
When the matching `libinput_device_config_set_FOO()` is called, this goes
through to the config struct and invokes the function there. Thus, it is
possible to have different configuration functions for a mouse vs a
touchpad, even though the interface is the same.
@dot
digraph context
{
compound=true;
rankdir="LR";
node [
shape="box";
]
libinput [label="libinput_device_config_accel_set_profile()"];
tablet_config [label="tablet_accel_config_set_profile()"];
libinput->tablet_config;
}
@enddot
@section architecture-filter Pointer acceleration filters
All pointer acceleration is handled in the `filter.c` file and its
associated files.
The `struct motion_filter` is initialized during device init, whenever
deltas are available they are passed to `filter_dispatch()`. This function
returns a set of @ref motion_normalization_customization "normalized coordinates".
All actual acceleration is handled within the filter, the device itself has
no further knowledge. Thus it is possible to have different acceleration
filters for the same device types (e.g. the Lenovo X230 touchpad has a
custom filter).
@dot
digraph context
{
compound=true;
rankdir="LR";
node [
shape="box";
]
fallback [label="fallback deltas"];
touchpad [label="touchpad deltas"];
tablet [label="tablet deltas"];
filter [label="filter_dispatch"];
fallback->filter;
touchpad->filter;
tablet->filter;
flat [label="accelerator_interface_flat()"];
x230 [label="accelerator_filter_x230()"];
pen [label="tablet_accelerator_filter_flat_pen()"];
filter->flat;
filter->x230;
filter->pen;
}
@enddot
Most filters convert the deltas (incl. timestamps) to a motion speed and
then apply a so-called profile function. This function returns a factor that
is then applied to the current delta, converting it into an accelerated
delta. See @ref pointer-acceleration for more details.
the current
*/
/**
@page building_libinput libinput build instructions
@tableofcontents
Instructions on how to build libinput and its tools and how to build against
libinput.
The build instruction on this page detail how to overwrite your
system-provided libinput with one from the git repository, see
see @ref reverting_install to revert to the previous state.
@section building Building libinput
libinput uses [meson](https://www.mesonbuild.com) and
[ninja](https://www.ninja-build.org). A build is usually the three-step
process below. A successful build requires the @ref
building_dependencies to be installed before running meson.
@verbatim
$> git clone https://gitlab.freedesktop.org/libinput/libinput
$> cd libinput
$> meson --prefix=/usr builddir/
$> ninja -C builddir/
$> sudo ninja -C builddir/ install
@endverbatim
When running libinput versions 1.11.x or earlier, you must run
@verbatim
$> sudo udevadm hwdb --update
@endverbatim
Additional options may also be specified. For example:
@verbatim
$> meson --prefix=/usr -Ddocumentation=false builddir/
@endverbatim
We recommend that users disable the documentation, it's not usually required
for testing and reduces the number of dependencies needed.
The `prefix` or other options can be changed later with the
`mesonconf` command. For example:
@verbatim
$> mesonconf builddir/ -Dprefix=/some/other/prefix -Ddocumentation=true
$> ninja -C builddir
$> sudo ninja -C builddir/ install
@endverbatim
Running ``mesonconf builddir/`` with no other arguments lists all
configurable options meson provides.
To rebuild from scratch, simply remove the build directory and run meson
again:
@verbatim
$> rm -r builddir/
$> meson --prefix=....
@endverbatim
@subsection verifying_install Verifying the install
To verify the install worked correctly, check that libinput.so.x.x.x is in
the library path and that all symlinks point to the new library.
@verbatim
$> ls -l /usr/lib64/libinput.*
-rwxr-xr-x 1 root root 946 Apr 28 2015 /usr/lib64/libinput.la
lrwxrwxrwx 1 root root 19 Feb 1 15:12 /usr/lib64/libinput.so -> libinput.so.10.13.0
lrwxrwxrwx 1 root root 19 Feb 1 15:12 /usr/lib64/libinput.so.10 -> libinput.so.10.13.0
-rwxr-xr-x 1 root root 204992 Feb 1 15:12 /usr/lib64/libinput.so.10.13.0
@endverbatim