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)')