DrathOrg/libratbag-plus
1
0
Fork 0
forked from drath/libratbag
Code Pull Requests Activity

Use Sphinx for the DBus interface documentation

Browse Source 
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 <peter.hutterer@who-t.net>
This commit is contained in:
Peter Hutterer
2017-10-11 14:25:25 +10:00
committed by Benjamin Tissoires
parent 1074a2b2e6
commit a535897ae7
10 changed files with 778 additions and 334 deletions
Download Patch File Download Diff File Expand all files Collapse all files

334
DBusInterface.md
View File

@@ -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.

24
circle.yml
View File

@@ -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

157
doc/conf.py.in Normal file
View File

@@ -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'),
]

430
doc/dbus.rst Normal file
View File

@@ -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 <https://github.com/libratbag/libratbag/blob/master/src/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.

53
doc/doxygen-enums-to-rst.xsl Normal file
View File

@@ -0,0 +1,53 @@
<!-- XSLT script to combine the generated output into a single file.
If you have xsltproc you could use:
xsltproc combine.xslt index.xml >all.xml
-->
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
<xsl:output method="text" indent="yes"/>
<xsl:strip-space elements="detaileddescription briefdescription"/>
<xsl:template match="/">
<xsl:text>
************
Enumerations
************
This document contains the enums used by libratbag's DBus interface.
</xsl:text>
<xsl:apply-templates select="//memberdef"/>
</xsl:template>
<xsl:template match="memberdef">
<xsl:value-of select="name"/>
---------------------------------------
<xsl:text>&#xa;</xsl:text>
<xsl:if test="briefdescription != ''">
<xsl:value-of select="briefdescription"/>
</xsl:if>
<xsl:if test="detaileddescription != ''">
<xsl:value-of select="detaileddescription"/>
</xsl:if>
.. cpp:enum:: <xsl:value-of select="name"/>
<xsl:text>&#xa;&#xa;</xsl:text>
<xsl:apply-templates select="./enumvalue"/>
</xsl:template>
<xsl:template match="enumvalue">
.. cpp:enumerator:: <xsl:value-of select="name"/><xsl:text> </xsl:text><xsl:value-of select="initializer"/>
<xsl:text>&#xa;&#xa;</xsl:text>
<xsl:if test="briefdescription != ''">
<xsl:text> </xsl:text><xsl:value-of select="briefdescription"/>
</xsl:if>
<xsl:if test="detaileddescription != ''">
<xsl:text> </xsl:text><xsl:value-of select="detaileddescription"/>
</xsl:if>
<xsl:text>&#xa;&#xa;</xsl:text>
</xsl:template>
</xsl:stylesheet>

20
doc/index.rst Normal file
View File

@@ -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 <dbus.rst>
Enumerations <enums.rst>
This document describes the DBus API that is the public interface for
libratbag.
Note: **the DBus interface is subject to change**

15
doc/libratbag.doxygen.in Normal file
View File

@@ -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

73
doc/meson.build Normal file
View File

@@ -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

1
meson.build
View File

@@ -539,3 +539,4 @@ configure_file(input : 'tools/toolbox.py',
#### output files ####
configure_file(output: 'config.h', install: false, configuration: config_h)
subdir('doc')

5
meson_options.txt
View File

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