docs: setup generation of gtk-doc based DBus API documentation

It includes gdbus-codegen generated API documentation, plus the common Enums,
Flags and Errors, which will also be used in libmm-glib.

.gitignore

@@ -12,6 +12,7 @@ ltmain.sh
 intltool-*
 missing
 stamp-h1
+gtk-doc.make
 *~
 *.o
 *.lo
@@ -61,6 +62,18 @@ po/insert-header.sin
 po/quot.sed
 po/remove-potcdate.sin
 
+docs/reference/api/version.xml
+docs/reference/api/mm.args
+docs/reference/api/mm.hierarchy
+docs/reference/api/mm.interfaces
+docs/reference/api/mm.prerequisites
+docs/reference/api/mm.signals
+docs/reference/api/*.stamp
+docs/reference/api/*.txt
+docs/reference/api/html
+docs/reference/api/tmpl
+docs/reference/api/xml
+
 m4/gtk-doc.m4
 m4/intltool.m4
 m4/libtool.m4

Makefile.am

@@ -1,5 +1,5 @@
 
-SUBDIRS = . marshallers build-aux include libmm-common libqcdm libwmc src plugins introspection po test
+SUBDIRS = . marshallers build-aux include libmm-common libqcdm libwmc src plugins introspection po test docs
 
 if WITH_POLKIT
 SUBDIRS += policy

autogen.sh

@@ -14,6 +14,7 @@ PKG_NAME=ModemManager
 }
 
 (cd $srcdir;
+    gtkdocize || exit 1
     autopoint --force
     AUTOPOINT='intltoolize --automake --copy' autoreconf --force --install --verbose
     if test -z "$NOCONFIGURE"; then

configure.ac

@@ -21,6 +21,23 @@ dnl Initialize libtool
 LT_PREREQ([2.2])
 LT_INIT
 
+dnl
+dnl Documentation
+dnl
+
+AC_ARG_WITH(docs, AS_HELP_STRING([--with-docs], [Build ModemManager documentation]))
+AM_CONDITIONAL(WITH_DOCS, test "x$with_docs" = "xyes")
+case $with_docs in
+    yes)
+        enable_gtk_doc=yes
+        ;;
+    *)
+        with_docs=no
+        ;;
+esac
+
+GTK_DOC_CHECK(1.0)
+
 dnl
 dnl translation support
 dnl
@@ -172,6 +189,10 @@ test/Makefile
 introspection/Makefile
 po/Makefile.in
 policy/Makefile
+docs/Makefile
+docs/reference/Makefile
+docs/reference/api/Makefile
+docs/reference/api/version.xml
 ])
 AC_OUTPUT
 

docs/Makefile.am

@@ -0,0 +1,2 @@
+
+SUBDIRS = reference

docs/reference/Makefile.am

@@ -0,0 +1,2 @@
+
+SUBDIRS = api

docs/reference/api/Makefile.am

@@ -0,0 +1,93 @@
+
+# The name of the module.
+DOC_MODULE = mm
+
+# The top-level SGML file.
+DOC_MAIN_SGML_FILE = $(DOC_MODULE)-docs.xml
+
+# Extra options to supply to gtkdoc-scan
+SCAN_OPTIONS =
+
+# The directory containing the source code.
+DOC_SOURCE_DIR = $(top_srcdir)/include
+
+HFILE_GLOB =
+CFILE_GLOB =
+
+# Headers to ignore
+IGNORE_HFILES = \
+	ModemManager.h \
+	ModemManager-names.h \
+	$(NULL)
+
+# CFLAGS and LDFLAGS for compiling scan program. Only needed
+# if $(DOC_MODULE).types is non-empty.
+INCLUDES = \
+	-I$(srcdir) \
+	-I$(top_srcdir) \
+	-I$(top_builddir) \
+	$(MM_CFLAGS) \
+	$(NULL)
+
+GTKDOC_LIBS = \
+	$(MM_LIBS) \
+	$(NULL)
+
+# Extra options to supply to gtkdoc-mkdb
+MKDB_OPTIONS = --output-format=xml --sgml-mode --name-space=mm
+
+# Images to copy into HTML directory
+HTML_IMAGES = \
+	$(NULL)
+
+content_files = \
+	$(NULL)
+
+expand_content_files = \
+	mm-overview.xml \
+	$(top_builddir)/libmm-common/mm-gdbus-doc-org.freedesktop.ModemManager1.xml \
+	$(top_builddir)/libmm-common/mm-gdbus-doc-org.freedesktop.ModemManager1.Sim.xml \
+	$(top_builddir)/libmm-common/mm-gdbus-doc-org.freedesktop.ModemManager1.Sms.xml \
+	$(top_builddir)/libmm-common/mm-gdbus-doc-org.freedesktop.ModemManager1.Bearer.xml \
+	$(top_builddir)/libmm-common/mm-gdbus-doc-org.freedesktop.ModemManager1.Modem.xml \
+	$(top_builddir)/libmm-common/mm-gdbus-doc-org.freedesktop.ModemManager1.Modem.Messaging.xml \
+	$(top_builddir)/libmm-common/mm-gdbus-doc-org.freedesktop.ModemManager1.Modem.Location.xml \
+	$(top_builddir)/libmm-common/mm-gdbus-doc-org.freedesktop.ModemManager1.Modem.Firmware.xml \
+	$(top_builddir)/libmm-common/mm-gdbus-doc-org.freedesktop.ModemManager1.Modem.Contacts.xml \
+	$(top_builddir)/libmm-common/mm-gdbus-doc-org.freedesktop.ModemManager1.Modem.Cdma.xml \
+	$(top_builddir)/libmm-common/mm-gdbus-doc-org.freedesktop.ModemManager1.Modem.3gpp.xml \
+	$(top_builddir)/libmm-common/mm-gdbus-doc-org.freedesktop.ModemManager1.Modem.3gpp.Ussd.xml \
+	$(top_builddir)/libmm-common/mm-gdbus-doc-org.freedesktop.ModemManager1.Modem.Simple.xml \
+	$(NULL)
+
+extra_files = \
+	$(NULL)
+
+if ENABLE_GTK_DOC
+include $(top_srcdir)/gtk-doc.make
+else
+EXTRA_DIST =
+CLEANFILES =
+endif
+
+EXTRA_DIST += \
+	mm-overview.xml \
+	version.xml.in \
+	$(NULL)
+
+CLEANFILES += \
+	$(DOC_MODULE)-decl-list.txt \
+	$(DOC_MODULE)-decl.txt \
+	$(DOC_MODULE)-overrides.txt \
+	$(DOC_MODULE)-undeclared.txt \
+	$(DOC_MODULE)-undocumented.txt \
+	$(DOC_MODULE)-overrides.txt \
+	$(DOC_MODULE)-unused.txt \
+	$(DOC_MODULE).args \
+	$(DOC_MODULE).hierarchy \
+	$(DOC_MODULE).interfaces \
+	$(DOC_MODULE).prerequisites \
+	$(DOC_MODULE).signals \
+	*.stamp \
+	-rf xml html tmpl \
+	$(NULL)

docs/reference/api/mm-docs.xml

@@ -0,0 +1,138 @@
+<?xml version="1.0"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
+<!ENTITY version SYSTEM "version.xml">
+]>
+<book id="mm" xmlns:xi="http://www.w3.org/2003/XInclude">
+  <bookinfo>
+    <title>ModemManager Reference Manual</title>
+    <releaseinfo>Version &version;</releaseinfo>
+
+    <copyright>
+      <year>2008</year>
+      <holder>Novell, Inc.</holder>
+    </copyright>
+    <copyright>
+      <year>2008</year>
+      <year>2009</year>
+      <year>2010</year>
+      <year>2011</year>
+      <holder>Red Hat, Inc.</holder>
+    </copyright>
+    <copyright>
+      <year>2011</year>
+      <holder>The Chromium OS Authors</holder>
+    </copyright>
+    <copyright>
+      <year>2011</year>
+      <holder>Google, Inc.</holder>
+    </copyright>
+
+    <legalnotice>
+      <para>
+        Permission is granted to copy, distribute and/or modify this
+        document under the terms of the <citetitle>GNU Free
+        Documentation License</citetitle>, Version 1.1 or any later
+        version published by the Free Software Foundation with no
+        Invariant Sections, no Front-Cover Texts, and no Back-Cover
+        Texts. You may obtain a copy of the <citetitle>GNU Free
+        Documentation License</citetitle> from the Free Software
+        Foundation by visiting <ulink type="http"
+        url="http://www.fsf.org">their Web site</ulink> or by writing
+        to:
+        <address>
+          <street>51 Franklin Street</street>, Suite 500
+          <city>Boston</city>, <state>MA</state> <postcode>02110-1335</postcode>
+          <country>USA</country>
+        </address>
+      </para>
+    </legalnotice>
+  </bookinfo>
+
+  <xi:include href="xml/mm-overview.xml"/>
+
+  <part id="ref-dbus">
+    <title>D-Bus API Reference</title>
+
+    <chapter id="ref-dbus-objects-names">
+      <title>Objects &amp; Names</title>
+      <sect1 id="ref-dbus-well-known-name">
+        <title>The <literal>org.freedesktop.ModemManager1</literal> bus name</title>
+        <para>
+          The D-Bus name <literal>org.freedesktop.ModemManager1</literal>
+          on the system bus is used by the ModemManager daemon. If this daemon
+          isn't running, it will be started if D-Bus messages are sent to the
+          name.
+        </para>
+      </sect1>
+      <sect1 id="ref-dbus-well-known-object">
+        <title>
+          The <literal>/org/freedesktop/ModemManager</literal>
+          and <literal>/org/freedesktop/ModemManager/Modems</literal> objects
+        </title>
+        <para>
+          The ModemManager process will export an object at the well-known
+          path <literal>/org/freedesktop/ModemManager1</literal>. This object can
+          be used to list available modem objects, which will also be exposed
+          on paths with the folowing pattern
+          <literal>/org/freedesktop/ModemManager1/Modems/#</literal>.
+        </para>
+      </sect1>
+    </chapter>
+
+    <chapter>
+      <title>Common types</title>
+      <xi:include href="xml/mm-enums.xml"/>
+      <xi:include href="xml/mm-errors.xml"/>
+    </chapter>
+    <chapter>
+      <title>Manager interface</title>
+      <xi:include href="../../../libmm-common/mm-gdbus-doc-org.freedesktop.ModemManager1.xml"/>
+    </chapter>
+    <chapter>
+      <title>SIM interface</title>
+      <xi:include href="../../../libmm-common/mm-gdbus-doc-org.freedesktop.ModemManager1.Sim.xml"/>
+    </chapter>
+    <chapter>
+      <title>SMS interface</title>
+      <xi:include href="../../../libmm-common/mm-gdbus-doc-org.freedesktop.ModemManager1.Sms.xml"/>
+    </chapter>
+    <chapter>
+      <title>Bearer interface</title>
+      <xi:include href="../../../libmm-common/mm-gdbus-doc-org.freedesktop.ModemManager1.Bearer.xml"/>
+    </chapter>
+    <chapter>
+      <title>Modem interfaces</title>
+      <section>
+        <title>Generic</title>
+        <xi:include href="../../../libmm-common/mm-gdbus-doc-org.freedesktop.ModemManager1.Modem.xml"/>
+        <xi:include href="../../../libmm-common/mm-gdbus-doc-org.freedesktop.ModemManager1.Modem.Simple.xml"/>
+      </section>
+      <section>
+        <title>3GPP specific</title>
+        <xi:include href="../../../libmm-common/mm-gdbus-doc-org.freedesktop.ModemManager1.Modem.3gpp.xml"/>
+        <xi:include href="../../../libmm-common/mm-gdbus-doc-org.freedesktop.ModemManager1.Modem.3gpp.Ussd.xml"/>
+      </section>
+      <section>
+        <title>CDMA specific</title>
+        <xi:include href="../../../libmm-common/mm-gdbus-doc-org.freedesktop.ModemManager1.Modem.Cdma.xml"/>
+      </section>
+      <section>
+        <title>Other</title>
+        <xi:include href="../../../libmm-common/mm-gdbus-doc-org.freedesktop.ModemManager1.Modem.Messaging.xml"/>
+        <xi:include href="../../../libmm-common/mm-gdbus-doc-org.freedesktop.ModemManager1.Modem.Location.xml"/>
+        <xi:include href="../../../libmm-common/mm-gdbus-doc-org.freedesktop.ModemManager1.Modem.Firmware.xml"/>
+        <xi:include href="../../../libmm-common/mm-gdbus-doc-org.freedesktop.ModemManager1.Modem.Contacts.xml"/>
+      </section>
+    </chapter>
+  </part>
+
+  <index>
+    <title>Index</title>
+  </index>
+
+  <chapter id="mm-hierarchy">
+    <title>Object Hierarchy</title>
+      <xi:include href="xml/tree_index.sgml"/>
+  </chapter>
+</book>

docs/reference/api/mm-overview.xml

@@ -0,0 +1,56 @@
+<?xml version="1.0"?>
+<!DOCTYPE part PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
+<!ENTITY version SYSTEM "version.xml">
+]>
+<part id="overview">
+  <title>ModemManager Overview</title>
+
+  <chapter id="overview-modemmanager">
+    <title>ModemManager</title>
+    <para>
+      ModemManager provides a unified high level API for communicating with
+      (mobile broadband) modems. While the basic commands are standardized,
+      the more advanced operations (like signal quality monitoring while
+      connected) varies a lot.
+    </para>
+
+    <formalpara>
+      <title>Using</title>
+      <para>
+        ModemManager is a system daemon and is not meant to be used directly from
+        the command line. However, since it provides DBus API, it is possible to use
+        'dbus-send' command to control it from the terminal. There's an example
+        program (tests/mm-test.py) that demonstrates the basic API usage.
+      </para>
+    </formalpara>
+
+    <formalpara>
+      <title>Implementation</title>
+      <para>
+        ModemManager is a DBus system bus activated service (meaning it's started
+        automatically when a request arrives). It is written in C. The devices are
+        queried from udev and automatically updated based on hardware events. There's
+        a GInterface (MMModem) that defines the modem interface and any device specific
+        implementation must implement it. There are two generic MMModem implementations
+        to support the basic operations (one for GSM, one for CDMA,) which are common
+        for all cards.
+      </para>
+    </formalpara>
+
+    <formalpara>
+      <title>Plugins</title>
+      <para>
+        Plugins are loaded on startup, and must implement the MMPlugin interface. It
+        consists of a couple of methods which tell the daemon whether the plugin
+        supports a port and to create custom MMModem implementations. It most likely
+        makes sense to derive custom modem implementations from one of the generic
+        classes and just add (or override) operations which are not standard. There's a
+        fully working plugin in the plugins/ directory for Huawei cards that can be
+        used as an example for writing new plugins. Writing new plugins is highly
+        encouraged!
+      </para>
+    </formalpara>
+
+  </chapter>
+</part>

docs/reference/api/mm-sections.txt

@@ -0,0 +1,32 @@
+<SECTION>
+<FILE>mm-enums</FILE>
+<TITLE>Flags and Enumerations</TITLE>
+MMBearerIpMethod
+MMModem3gppFacility
+MMModem3gppNetworkAvailability
+MMModem3gppRegistrationState
+MMModem3gppUssdSessionState
+MMModemAccessTech
+MMModemBand
+MMModemCapability
+MMModemCdmaActivationError
+MMModemCdmaActivationState
+MMModemCdmaRegistrationState
+MMModemContactsStorage
+MMModemLocationSource
+MMModemLock
+MMModemMode
+MMModemSmsState
+MMModemState
+MMModemStateChangeReason
+</SECTION>
+
+<SECTION>
+<FILE>mm-errors</FILE>
+<TITLE>Errors</TITLE>
+MMConnectionError
+MMCoreError
+MMMessageError
+MMMobileEquipmentError
+MMSerialError
+</SECTION>

docs/reference/api/version.xml.in

@@ -0,0 +1 @@
+@VERSION@