From a535897ae71c4bbfb336be274c3ce0794744885b Mon Sep 17 00:00:00 2001 From: Peter Hutterer Date: Wed, 11 Oct 2017 14:25:25 +1000 Subject: [PATCH] Use Sphinx for the DBus interface documentation Better than the markdown we were using before, even though we're currently (ab)using the js/c++ domains for the structure. There is no DBus domain in sphinx yet. The main motivation was to get the enums into the documentation since they are exported ABI. Generating the documentation is quirky - we use doxygen to extract the comments from the C header file and then use XSLT to convert to .rst which sphinx can use. Still better than having to maintain even more copies of the enums. Since this is only of interest for maintainers that need to upload the documentation, it is turned off by default. Signed-off-by: Peter Hutterer --- DBusInterface.md | 334 --------------------------- circle.yml | 24 ++ doc/conf.py.in | 157 +++++++++++++ doc/dbus.rst | 430 +++++++++++++++++++++++++++++++++++ doc/doxygen-enums-to-rst.xsl | 53 +++++ doc/index.rst | 20 ++ doc/libratbag.doxygen.in | 15 ++ doc/meson.build | 73 ++++++ meson.build | 1 + meson_options.txt | 5 + 10 files changed, 778 insertions(+), 334 deletions(-) delete mode 100644 DBusInterface.md create mode 100644 doc/conf.py.in create mode 100644 doc/dbus.rst create mode 100644 doc/doxygen-enums-to-rst.xsl create mode 100644 doc/index.rst create mode 100644 doc/libratbag.doxygen.in create mode 100644 doc/meson.build diff --git a/DBusInterface.md b/DBusInterface.md deleted file mode 100644 index 68b0fc70..00000000 --- a/DBusInterface.md +++ /dev/null @@ -1,334 +0,0 @@ -The ratbagd DBus-Interface --------------------------- - -Note: **the DBus interface is subject to change** - -Interfaces: -- org.freedesktop.ratbag1.Manager -- org.freedesktop.ratbag1.Device -- org.freedesktop.ratbag1.Profile -- org.freedesktop.ratbag1.Resolution -- org.freedesktop.ratbag1.Button -- org.freedesktop.ratbag1.Led - -For a list of dbus types as used below, see https://dbus.freedesktop.org/doc/dbus-specification.html - -Properties marked as 'constant' do not change for the lifetime of the -object. Properties marked as 'mutable' may change, and a -`org.freedesktop.DBus.Properties.PropertyChanged` signal is sent for those -unless otherwise specified. - -All setters (whether implicit for read-write properties or explicit) return -success instead of the internal return value because DBus does not like -non-standard error values. Upon a ratbag error, the `Resync` signal is emitted -on the device, indicating that clients should resync their values. - -Values listed as enums are defined in [libratbag-enums.h](https://github.com/libratbag/libratbag/blob/master/src/libratbag-enums.h) - -org.freedesktop.ratbag1.Manager -=============================== - -The **org.freedesktop.ratbag1.Manager** interface is the entry point to -interact with ratbagd. - -### Properties: - -#### `Devices` -- type `ao`, read-only, mutable - -Provides the object paths of all current devices, see **org.freedesktop.ratbag1.Device** - -#### `Themes` -- type `as`, read-only, constant - -Provides the list of available theme names. This list is guaranteed to have -one theme available ('default'). Other themes are implementation defined. -A theme listed here is only a guarantee that the theme is known to libratbag -and that SVGs *may* exist, it is not a guarantee that the SVG for any -specific device exists. In other words, a device may not have an SVG for a -specific theme. - -This list is static for the lifetime of ratbagd. - -org.freedesktop.ratbag1.Device -============================== - -The **org.freedesktop.ratbag1.Device** interface describes a single device -known to ratbagd. - -### Properties: - -#### `Id` -- type: `s`, read-only, constant - -An ID describing this device. This ID should not be used for presentation to -the user. This ID is unique for the device for the lifetime of the device -but may be recycled when the device is removed. No guarantee is given for -the content of the ID, the client should treat it as an opaque string. - -#### `Description` -- type: `s`, read-only, constant - -The device's name, suitable for presentation to the user. - -#### `Capabilities` -- type: `au`, read-only, constant - -The capabilities supported by this device. see `enum -ratbag_device_capability` in libratbag-enums.h for the list of permissible -capabilities. - - -#### `Svg` -- type: `s`, read-only, constant - -The device's SVG file name, without path. - -#### `Profiles` -- type: `ao`, read-only, mutable - -This property is mutable if the device supports adding and removing -profiles. - -Provides the list of profile paths for all profiles on this device, see -**org.freedesktop.ratbag1.Profile**. - -### Methods: - -#### `Commit() → ()` - -Commits the changes to the device. Changes to the device are batched; they -are not written to the hardware until `Commit()` is invoked. - -#### `GetSvg(s) → (s)` - -Returns the full path to the SVG for the given theme or an empty string if -none is available. The theme must be one of -**org.freedesktop.ratbag1.Manager.Themes**. The theme 'default' is -guaranteed to be available. ratbagd may return the path to a file that -doesn't exist. This is the case if the device has SVGs available but not for -the given theme. - -### Signals: - -#### `Resync()` - -Emitted when an internal error occurs. Upon receiving this signal, clients are -expected to resync their values with ratbagd. - -org.freedesktop.ratbag1.Profile -=============================== - -### Properties: - -#### `Index` -- type: `u`, read-only, constant - -The index of this profile - -#### `Name` -- type: `s`, read-write, mutable - -The name of this profile. - -#### `Enabled` -- type: `b`, read-write, mutable - -True if this is the profile is enabled, false otherwise. - -Note that a disabled profile might not have correct bindings, so it's -a good thing to rebind everything before calling `Commit()` on the -**org.freedesktop.ratbag1.Device**. - -#### `Resolutions` -- type: `ao`, read-only, mutable - -This property is mutable if the device supports adding and removing -resolutions. - -Provides the object paths of all resolutions in this profile, see -**org.freedesktop.ratbag1.Resolution** - -#### `Buttons` -- type: `ao`, read-only, constant - -Provides the object paths of all buttons in this profile, see -**org.freedesktop.ratbag1.Button** - -#### `Leds` -- type: `ao`, read-only, constant - -Provides the object paths of all LEDs in this profile, see -**org.freedesktop.ratbag1.Led** - -### `IsActive` -- type: `b`, read-only, mutable - -True if this is the currently active profile, false otherwise. - -Profiles can only be set to active, but never to not active - at least one -profile must be active at all times. This property is read-only, use the -`SetActive()` method to activate a profile. - -### Methods: - -#### `SetActive() → ()` -Set this profile to be the active profile - -org.freedesktop.ratbag1.Resolution -================================== - -### Properties: -#### `Index` -- type: `u`, read-only, constant - -Index of the resolution -#### `Capabilities` -- type: `au`, read-only, constant - -Array of uints from the ratbag\_resolution\_capability from libratbag.h. - -#### `IsActive` -- type: `b`, read-only, mutable - -True if this is the currently active resolution, false otherwise. - -Resolutions can only be set to active, but never to not active - at least -one resoultion must be active at all times. This property is read-only, use the -`SetActive()` method to set a resolution as the active resolution. - -#### `IsDefault` -- type: `b`, read-only, mutable - -True if this is the currently default resolution, false otherwise. If the -device does not have the default resolution capability, this property is -always false. - -Resolutions can only be set to default, but never to not default - at least -one resolution must be default at all times. This property is read-only, use the -`SetDefault()` method to set a resolution as the default resolution. - -#### `Resolution` -- type: `uu`, read-write, mutable - -uint for the x and y resolution assigned to this entry, respectively. -The value for the resolution must be equal to or between the `Minimum` and -`Maximum` of this resolution. - -If the resolution does not support separate x/y resolutions, x and y must -be the same value. - -#### `ReportRate` -- type: `u`, read-write, mutable - -uint for the report rate in Hz assigned to this entry - -If the resolution does not have the individual report rate capability, -changing the report rate on one resolution will change the report rate on -all resolutions. - -#### `Maximum` -- type: `u`, read-only, constant - -uint for the maximum resolution - -#### `Minimum` -- type: `u`, read-only, constant - -uint for the minimum possible resolution - -### Methods: - -#### `SetDefault() → () ` - -Set this resolution to be the default -#### `SetActive() → () ` - -Set this resolution to be the active one - -org.freedesktop.ratbag1.Button -============================== - -### Properties: -#### `Index` -- type: `u`, read-only, constant - -Index of the button -#### `Type` -- type: `u`, read-only, constant - -Enum describing the button physical type. This type is unrelated to the -logical button mapping and serves to easily identify the button on the -device. -#### `ButtonMapping` -- type: `u`, read-write, mutable - -uint of the current button mapping (if mapping to button) -#### `SpecialMapping` -- type: `u`, read-write, mutable - -Enum describing the current special mapping (if mapped to special) -#### `Macro` --type: `a(uu)`, read-write, mutable - -Array of (type, keycode), where type may be one of -`RATBAG_MACRO_EVENT_KEY_PRESSED` or `RATBAG_MACRO_EVENT_KEY_RELEASED`. -#### `ActionType` -- type: `u`, read-only, mutable - -An enum describing the action type of the button, see -ratbag\_button\_get\_action\_type for the list of enums. -This decides which *Mapping* property has a value. -#### `ActionTypes` -- type: `au`, read-only, constant -Array of enum ratbag\_button\_action\_type, possible values for ActionType -on the current device - -### Methods: -#### `Disable() → ()` -Disable this button - -org.freedesktop.ratbag1.Led -=========================== - -### Properties: -#### `Index` -- type: `u`, read-only, constant - -Index of the LED - -#### `Mode` -- type: `u`, read-write, mutable - -uint mapping to the mode enum from libratbag - -#### `Type` -- type: `u`, read-only, mutable - -enum describing the LED type - -#### `Color` -- type: `(uuu)`, read-write, mutable -uint triplet (RGB) of the LED's color - -#### `ColorDepth` -- type: `u`, read-only, constant - -The color depth of this LED as one of the constants in libratbag-enums.h - -#### `EffectRate` -- type: `u`, read-write, mutable - -The effect rate in Hz, possible values are in the range 100 - 20000 - -#### `Brightness` -- type: `u`, read-write, mutable - -The brightness of the LED, possible values are in the range 0 - 255 - -For easier debugging, objects paths are constructed from the device. e.g. -`/org/freedesktop/ratbag/button/event5/p0/b10` is the button interface for -button 10 on profile 0 on event5. The naming is subject to change. Do not -rely on a constructed object path in your application. - - diff --git a/circle.yml b/circle.yml index 34ef8c88..f2425e29 100644 --- a/circle.yml +++ b/circle.yml @@ -1,3 +1,4 @@ +# vim: set expandtab shiftwidth=2 tabstop=8: libratbag_references: default_settings: &default_settings working_directory: ~/libratbag @@ -18,6 +19,12 @@ libratbag_references: name: Build and test environment: NINJA_ARGS: test + build_with_docs: &build_with_docs + run: + <<: *build_default + name: Build with documentation + environment: + MESON_PARAMS: -Ddocumentation=true install: &install run: name: Installing @@ -106,6 +113,18 @@ scan_build_run: &scan_build_run name: Check scan-build results command: test ! -d ~/libratbag/build/meson-logs/scanbuild || test $(find ~/libratbag/build/meson-logs/scanbuild -maxdepth 0 ! -empty -exec echo "not empty" \; | wc -l) -eq 0 || (echo "Check scan-build results" && false) +doc_build: &doc_build + <<: *default_settings + steps: + - *fedora_install + - run: + name: Install documentation build-deps + command: dnf install -y python3-sphinx python3-sphinx_rtd_theme doxygen libxslt + - checkout + - *build_with_docs + - *export_logs + - store_artifacts: + path: ~/libratbag/build/doc/html version: 2 jobs: @@ -121,6 +140,10 @@ jobs: <<: *ubuntu_settings docker: - image: ubuntu:zesty + doc_build: + <<: *doc_build + docker: + - image: fedora:latest scan_build: <<: *scan_build_run docker: @@ -135,3 +158,4 @@ workflows: - scan_build - ubuntu_17_04 - fedora_latest + - doc_build diff --git a/doc/conf.py.in b/doc/conf.py.in new file mode 100644 index 00000000..010094fe --- /dev/null +++ b/doc/conf.py.in @@ -0,0 +1,157 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8 -*- +# +# @PACKAGE_NAME@ documentation build configuration file, created by +# sphinx-quickstart on Wed Oct 11 13:45:08 2017. +# +# This file is execfile()d with the current directory set to its +# containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. + +import os +import sys +sys.path.insert(0, os.path.abspath('..')) + +# -- General configuration ------------------------------------------------ + +# If your documentation needs a minimal Sphinx version, state it here. +# +# needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix(es) of source filenames. +# You can specify multiple suffix as a list of string: +# +# source_suffix = ['.rst', '.md'] +source_suffix = '.rst' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = '@PACKAGE_NAME@' +copyright = '2017, The ratbaggers' +author = 'The ratbaggers' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = '' +# The full version, including alpha/beta/rc tags. +release = '' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = None + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This patterns also effect to html_static_path and html_extra_path +exclude_patterns = [] + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# If true, `todo` and `todoList` produce output, else they produce nothing. +todo_include_todos = False + + +# -- Options for HTML output ---------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +# html_theme = 'alabaster' +html_theme = 'sphinx_rtd_theme' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +# +# html_theme_options = {} + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + + +# -- Options for HTMLHelp output ------------------------------------------ + +# Output file base name for HTML help builder. +htmlhelp_basename = '@PACKAGE_NAME@doc' + + +# -- Options for LaTeX output --------------------------------------------- + +latex_elements = { + # The paper size ('letterpaper' or 'a4paper'). + # + # 'papersize': 'letterpaper', + + # The font size ('10pt', '11pt' or '12pt'). + # + # 'pointsize': '10pt', + + # Additional stuff for the LaTeX preamble. + # + # 'preamble': '', + + # Latex figure (float) alignment + # + # 'figure_align': 'htbp', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + (master_doc, '@PACKAGE_NAME@.tex', '@PACKAGE_NAME@ Documentation', + 'The ratbaggers', 'manual'), +] + + +# -- Options for manual page output --------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + (master_doc, '@PACKAGE_NAME@', '@PACKAGE_NAME@ Documentation', + [author], 1) +] + + +# -- Options for Texinfo output ------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + (master_doc, '@PACKAGE_NAME@', '@PACKAGE_NAME@ Documentation', + author, '@PACKAGE_NAME@', 'One line description of project.', + 'Miscellaneous'), +] + + + diff --git a/doc/dbus.rst b/doc/dbus.rst new file mode 100644 index 00000000..ed3cdb0f --- /dev/null +++ b/doc/dbus.rst @@ -0,0 +1,430 @@ +******** +DBus API +******** + +Note: **the DBus interface is subject to change** + +Interfaces: + +* org.freedesktop.ratbag1.Manager +* org.freedesktop.ratbag1.Device +* org.freedesktop.ratbag1.Profile +* org.freedesktop.ratbag1.Resolution +* org.freedesktop.ratbag1.Button +* org.freedesktop.ratbag1.Led + +For a list of dbus types as used below, see https://dbus.freedesktop.org/doc/dbus-specification.html + +Properties marked as **constant** do not change for the lifetime of the +object. Properties marked as **mutable** may change, and a +``org.freedesktop.DBus.Properties.PropertyChanged`` signal is sent for those +unless otherwise specified. + +All setters (whether implicit for read-write properties or explicit) return +success instead of the internal return value because DBus does not like +non-standard error values. Upon a ratbag error, the `Resync` signal is emitted +on the device, indicating that clients should resync their values. + +Values listed as enums are defined in `libratbag-enums.h `_ + +org.freedesktop.ratbag1.Manager +------------------------------- + +.. js:class:: Manager + + The **org.freedesktop.ratbag1.Manager** interface is the entry point to + interact with ratbagd. + + .. js:attribute:: Devices + + :type: ao + + An array of read-only **object paths** to :js:class:`Device` objects + + .. js:attribute:: Themes + + :type: as + + :flags: read-only, constant + + Provides the list of available theme names. This list is guaranteed to have + one theme available ('default'). Other themes are implementation defined. + A theme listed here is only a guarantee that the theme is known to libratbag + and that SVGs *may* exist, it is not a guarantee that the SVG for any + specific device exists. In other words, a device may not have an SVG for a + specific theme. + + This list is static for the lifetime of ratbagd. + +org.freedesktop.ratbag1.Device +------------------------------- + +.. js:class:: Device + + The **org.freedesktop.ratbag1.Device** interface describes a single device + known to ratbagd. + + .. js:attribute:: Id + + :type: as + + :flags: read-only, constant + + An ID describing this device. This ID should not be used for presentation to + the user. This ID is unique for the device for the lifetime of the device + but may be recycled when the device is removed. No guarantee is given for + the content of the ID, the client should treat it as an opaque string. + + .. js:attribute:: Description + + :type: s + :flags: read-only, constant + + The device's name, suitable for presentation to the user. + + .. js:attribute:: Capabilities + + :type: au + :flags: read-only, constant + + The capabilities supported by this device. see `enum + ratbag_device_capability` in libratbag-enums.h for the list of permissible + capabilities. + + + .. js:attribute:: Svg + + :type: s + :flags: read-only, constant + + The device's SVG file name, without path. + + .. js:attribute:: Profiles + + :type: ao + :flags: read-only, mutable + + This property is mutable if the device supports adding and removing + profiles. + + Provides the list of profile paths for all profiles on this device, see + :js:class:`Profile`. + + .. js:function:: Commit() → () + + Commits the changes to the device. Changes to the device are batched; they + are not written to the hardware until :js:func:`Commit()` is invoked. + + .. js:function:: GetSvg(s) → (s) + + :param s: the theme name + :returns: A full path to the SVG for the given theme + + Returns the full path to the SVG for the given theme or an + empty string if none is available. The theme must be one of + :js:attr:`Themes`. + + The theme **'default'** is guaranteed to be available. + ratbagd may return the path to a file that doesn't exist. + This is the case if the device has SVGs available but not + for the given theme. + + .. js:function:: Resync() + + :type: Signal + + Emitted when an internal error occurs. Upon receiving this + signal, clients are expected to resync their values with + ratbagd. + + +org.freedesktop.ratbag1.Profile +------------------------------- + +.. js:class:: Profile + + .. js:attribute:: Index + + :type: u + :flags: read-only, constant + + The index of this profile + + .. js:attribute:: Name + + :type: s + :flags: read-write, mutable + + The name of this profile. + + .. js:attribute:: Enabled + + :type: b + :flags: read-write, mutable + + True if this is the profile is enabled, false otherwise. + + Note that a disabled profile might not have correct bindings, so it's + a good thing to rebind everything before calling :js:func:`Commit()` on the + :js:class:`Device`. + + .. js:attribute:: Resolutions + + :type: ao + :flags: read-only, mutable + + This property is mutable if the device supports adding and removing + resolutions. + + Provides the object paths of all resolutions in this profile, see + :js:class:`Resolution` + + .. js:attribute:: Buttons + + :type: ao + :flags: read-only, constant + + Provides the object paths of all buttons in this profile, see + :js:class:`Button` + + .. js:attribute:: Leds + + :type: ao + :flags: read-only, constant + + Provides the object paths of all LEDs in this profile, see + :js:class:`Led` + + .. js:attribute:: IsActive + + :type: b + :flags: read-only, mutable + + True if this is the currently active profile, false otherwise. + + Profiles can only be set to active, but never to not active - at least one + profile must be active at all times. This property is read-only, use the + :js:func:`SetActive()` method to activate a profile. + + .. js:function:: SetActive() → () + + Set this profile to be the active profile + +org.freedesktop.ratbag1.Resolution +---------------------------------- + +.. js:class:: Resolution + + .. js:attribute:: Index + + :type: u + :flags: read-only, constant + + Index of the resolution + + .. js:attribute:: Capabilities + + :type: au + :flags: read-only, constant + + Array of uints from the ratbag\_resolution\_capability from libratbag.h. + + .. js:attribute:: IsActive + + :type: b + :flags: read-only, mutable + + True if this is the currently active resolution, false otherwise. + + Resolutions can only be set to active, but never to not + active - at least one resoultion must be active at all + times. This property is read-only, use the + :js:func:`SetActive()` method to set a resolution as the + active resolution. + + .. js:attribute:: IsDefault + + :type: b + :flags: read-only, mutable + + True if this is the currently default resolution, false + otherwise. If the device does not have the default + resolution capability, this property is always false. + + Resolutions can only be set to default, but never to not + default - at least one resolution must be default at all + times. This property is read-only, use the + :js:func:`SetDefault()` method to set a resolution as + the default resolution. + + .. js:attribute:: Resolution + + :type: uu + :flags: read-write, mutable + + uint for the x and y resolution assigned to this entry, + respectively. The value for the resolution must be equal to + or between the :js:attr:`Minimum` and :js:attr:`Maximum` of + this resolution. + + If the resolution does not support separate x/y resolutions, + x and y must be the same value. + + .. js:attribute:: ReportRate + + :type: u + :flags: read-write, mutable + + uint for the report rate in Hz assigned to this entry + + If the resolution does not have the individual report rate + capability, changing the report rate on one resolution will + change the report rate on all resolutions. + + .. js:attribute:: Maximum + + :type: u + :flags: read-only, constant + + uint for the maximum resolution + + .. js:attribute:: Minimum + + :type: u + :flags: read-only, constant + + uint for the minimum possible resolution + + .. js:function:: SetDefault() → () + + Set this resolution to be the default + + .. js:function:: SetActive() → () + + Set this resolution to be the active one + +org.freedesktop.ratbag1.Button +------------------------------ + +.. js:class:: Button + + .. js:attribute:: Index + + :type: u + :flags: read-only, constant + + Index of the button + + .. js:attribute:: Type + + :type: u + :flags: read-only, constant + + Enum describing the button physical type, see + :cpp:enum:`ratbag_button_type`. This type is unrelated to the + logical button mapping and serves to easily identify the button on + the device. + + .. js:attribute:: ButtonMapping + + :type: u + :flags: read-write, mutable + + uint of the current button mapping (if mapping to button) + + .. js:attribute:: SpecialMapping + + :type: u + :flags: read-write, mutable + + Enum describing the current special mapping (if mapped to special) + + .. js:attribute:: Macro + + :type: a(uu) + :flags: read-write, mutable + + Array of (type, keycode), where type may be one of + :cpp:enumerator:`RATBAG_MACRO_EVENT_KEY_PRESSED` or + :cpp:enumerator:`RATBAG_MACRO_EVENT_KEY_RELEASED`. + + .. js:attribute:: ActionType + + :type: u + :flags: read-only, mutable + + An enum describing the action type of the button, see + :cpp:enum:`ratbag_button_action_type` for the list of enums. + This decides which one of :js:attr:`ButtonMapping`, + :js:attr:`SpecialMapping` and :js:attr:`Macro` has a value. + + .. js:attribute:: ActionTypes + + :type: au + :flags: read-only, constant + + Array of :cpp:enum:`ratbag_button_action_type`, possible values + for ActionType on the current device + + .. js:function:: Disable() → () + + Disable this button + +org.freedesktop.ratbag1.Led +--------------------------- + +.. js:class:: Led + + .. js:attribute:: Index + + :type: u + :flags: read-only, constant + + Index of the LED + + .. js:attribute:: Mode + + :type: u + :flags: read-write, mutable + + uint mapping to the mode enum from libratbag + + .. js:attribute:: Type + + :type: u + :flags: read-only, mutable + + enum describing the LED type + + .. js:attribute:: Color + + :type: (uuu) + :flags: read-write, mutable + + uint triplet (RGB) of the LED's color + + .. js:attribute:: ColorDepth + + :type: u + :flags: read-only, constant + + The color depth of this LED as one of the constants in libratbag-enums.h + + .. js:attribute:: EffectRate + + :type: u + :flags: read-write, mutable + + The effect rate in Hz, possible values are in the range 100 - 20000 + + .. js:attribute:: Brightness + + :type: u + :flags: read-write, mutable + + The brightness of the LED, possible values are in the range 0 - 255 + +For easier debugging, objects paths are constructed from the device. e.g. +`/org/freedesktop/ratbag/button/event5/p0/b10` is the button interface for +button 10 on profile 0 on event5. The naming is subject to change. Do not +rely on a constructed object path in your application. diff --git a/doc/doxygen-enums-to-rst.xsl b/doc/doxygen-enums-to-rst.xsl new file mode 100644 index 00000000..3cc912f9 --- /dev/null +++ b/doc/doxygen-enums-to-rst.xsl @@ -0,0 +1,53 @@ + + + + + + + +************ +Enumerations +************ + +This document contains the enums used by libratbag's DBus interface. + + + + + + + + +--------------------------------------- + + + + + + + + + +.. cpp:enum:: + + + + + + + + .. cpp:enumerator:: + + + + + + + + + + + diff --git a/doc/index.rst b/doc/index.rst new file mode 100644 index 00000000..0076ffa1 --- /dev/null +++ b/doc/index.rst @@ -0,0 +1,20 @@ +.. libratbag documentation master file, created by + sphinx-quickstart on Wed Oct 11 13:45:08 2017. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +********************** +The libratbag DBus API +********************** + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + The DBus Interfaces + Enumerations + +This document describes the DBus API that is the public interface for +libratbag. + +Note: **the DBus interface is subject to change** diff --git a/doc/libratbag.doxygen.in b/doc/libratbag.doxygen.in new file mode 100644 index 00000000..d8f6c500 --- /dev/null +++ b/doc/libratbag.doxygen.in @@ -0,0 +1,15 @@ +PROJECT_NAME = @PACKAGE_NAME@ +PROJECT_NUMBER = @PACKAGE_VERSION@ +PROJECT_BRIEF = "A mouse configuration library" +JAVADOC_AUTOBRIEF = YES +TAB_SIZE = 8 +OPTIMIZE_OUTPUT_FOR_C = YES +EXTRACT_ALL = YES +EXTRACT_STATIC = YES +MAX_INITIALIZER_LINES = 0 +QUIET = YES +# Keep this list in sync with meson.build +INPUT = @top_srcdir@/src/libratbag-enums.h +GENERATE_HTML = NO +GENERATE_XML = YES +GENERATE_LATEX = NO diff --git a/doc/meson.build b/doc/meson.build new file mode 100644 index 00000000..c2ff423a --- /dev/null +++ b/doc/meson.build @@ -0,0 +1,73 @@ +if get_option('documentation') + +cmd_sphinx = find_program('sphinx-build-3') +cmd_doxygen = find_program('doxygen') +cmd_xsltproc = find_program('xsltproc') + +doc_config = configuration_data() +doc_config.set('PACKAGE_NAME', meson.project_name()) +doc_config.set('PACKAGE_VERSION', meson.project_version()) +doc_config.set('top_srcdir', meson.source_root()) + +# We have a dependency chain here: +# - generate doxygen xml from the source +# - convert the xml to rst with xstlproc +# - generate the sphinx conf +# - run sphinx against the generated rst +doxyfile = configure_file(input : 'libratbag.doxygen.in', + output : 'libratbag.doxygen', + configuration : doc_config, + install : false) + +src_doxygen = [ doxyfile, + files('../src/libratbag-enums.h') ] +doxygen = custom_target('doxygen', + input : src_doxygen, + output : [ 'xml' ], + command : [ cmd_doxygen, doxyfile ], + install : false, + build_by_default : true) + + +# Sphinx really really wants a _static directory in its source tree. Let's +# make it happy +run_command('mkdir', '-p', join_paths(meson.build_root(), 'doc', '_static')) + +xsl = join_paths(meson.source_root(), 'doc', 'doxygen-enums-to-rst.xsl') +src_xsltproc = join_paths(meson.build_root(), 'xml', 'group__enums.xml') +dst_xstlproc = join_paths(meson.build_root(), 'doc', 'enums.rst') +rst_enum = custom_target('xsltproc', + input : doxygen, + output : 'enums.rst', + command: [ cmd_xsltproc, '-o', dst_xstlproc, xsl, src_xsltproc], + build_by_default : true) + +# Effectively a noop copy. We *must* generate enums.rst so that will end up +# in the build directory. sphinx doesn't allow for multiple source +# directories, so any .rst and the conf.py must be copied over to the +# build directory too +src_rsts = ['index.rst', 'dbus.rst'] +dst_rsts = [rst_enum] +foreach rst : src_rsts + f = configure_file(input : rst, + output : rst, + configuration : doc_config, + install : false) + dst_rsts += f +endforeach + +sphinx_conf = configure_file(input : 'conf.py.in', + output : 'conf.py', + configuration : doc_config, + install : false) + +custom_target('sphinx', + input : [ sphinx_conf, dst_rsts ], + output : 'html', + command : [ cmd_sphinx, '-b', 'html', '-q', '-n', + join_paths(meson.build_root(), 'doc'), + join_paths(meson.build_root(), 'doc', 'html') ], + build_by_default : true, + install : false) + +endif diff --git a/meson.build b/meson.build index d92bd15a..69823c1b 100644 --- a/meson.build +++ b/meson.build @@ -539,3 +539,4 @@ configure_file(input : 'tools/toolbox.py', #### output files #### configure_file(output: 'config.h', install: false, configuration: config_h) +subdir('doc') diff --git a/meson_options.txt b/meson_options.txt index e4c8ec47..f761ad8e 100644 --- a/meson_options.txt +++ b/meson_options.txt @@ -17,3 +17,8 @@ option('dbus-root-dir', type : 'string', value : '', description : 'dbus service directory [default=$datadir/dbus-1]') + +option('documentation', + type: 'boolean', + value: false, + description: 'Enable documentation build (default=no)')