[gnome-software] Enable gtk-doc generation for documentation

[Richard Hughes <rhughes src gnome org>]

commit 79cf52e11078792540c6fc24b3c2bbd8f6ee7c24
Author: Richard Hughes <richard hughsie com>
Date:   Fri May 20 09:44:35 2016 +0100

    Enable gtk-doc generation for documentation

 Makefile.am                     |    4 ++
 configure.ac                    |    2 +
 contrib/gnome-software.spec.in  |    2 +-
 doc/Makefile.am                 |    3 +
 doc/api/Makefile.am             |  109 +++++++++++++++++++++++++++++++++++++++
 doc/api/gnome-software-docs.xml |   17 ++++++
 doc/update.sh                   |    1 +
 src/gs-plugin-vfuncs.h          |    9 +++
 src/gs-plugin.c                 |    2 +-
 9 files changed, 147 insertions(+), 2 deletions(-)
---
diff --git a/Makefile.am b/Makefile.am
index eeff83f..63e78c0 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -4,6 +4,9 @@ SUBDIRS =                                               \
        src                                             \
        tests
 
+# we need objects in src
+SUBDIRS += doc
+
 snapshot:
        $(MAKE) dist distdir=$(PACKAGE)-$(VERSION)-`date +"%Y%m%d"`
 
@@ -40,6 +43,7 @@ EXTRA_DIST =                                          \
        README
 
 DISTCHECK_CONFIGURE_FLAGS =                            \
+       --enable-gtk-doc                                \
        --disable-tests                                 \
        --disable-dogtail
 
diff --git a/configure.ac b/configure.ac
index 45fb6b0..c1d0da9 100644
--- a/configure.ac
+++ b/configure.ac
@@ -334,6 +334,8 @@ data/icons/hicolor/48x48/Makefile
 data/icons/hicolor/256x256/Makefile
 data/icons/hicolor/scalable/Makefile
 data/tests/Makefile
+doc/Makefile
+doc/api/Makefile
 src/gnome-software.pc
 src/Makefile
 src/plugins/Makefile
diff --git a/contrib/gnome-software.spec.in b/contrib/gnome-software.spec.in
index b212883..833bb6e 100644
--- a/contrib/gnome-software.spec.in
+++ b/contrib/gnome-software.spec.in
@@ -138,7 +138,7 @@ glib-compile-schemas %{_datadir}/glib-2.0/schemas &> /dev/null || :
 %{_libdir}/pkgconfig/gnome-software.pc
 %dir %{_includedir}/gnome-software
 %{_includedir}/gnome-software/*.h
-#%{_datadir}/gtk-doc/html/gnome-software
+%{_datadir}/gtk-doc/html/gnome-software
 
 %changelog
 * #LONGDATE# Richard Hughes <richard hughsie com> #VERSION#-0.#BUILD##ALPHATAG#
diff --git a/doc/Makefile.am b/doc/Makefile.am
new file mode 100644
index 0000000..995c104
--- /dev/null
+++ b/doc/Makefile.am
@@ -0,0 +1,3 @@
+SUBDIRS = api
+
+-include $(top_srcdir)/git.mk
diff --git a/doc/api/Makefile.am b/doc/api/Makefile.am
new file mode 100644
index 0000000..6953b9d
--- /dev/null
+++ b/doc/api/Makefile.am
@@ -0,0 +1,109 @@
+# This is a blank Makefile.am for using gtk-doc.
+# Copy this to your project's API docs directory and modify the variables to
+# suit your project. See the GTK+ Makefiles in gtk+/docs/reference for examples
+# of using the various options.
+
+# The name of the module, e.g. 'glib'.
+DOC_MODULE=gnome-software
+
+# Uncomment for versioned docs and specify the version of the module, e.g. '2'.
+#DOC_MODULE_VERSION=2
+
+# The top-level XML file.
+DOC_MAIN_SGML_FILE=$(DOC_MODULE)-docs.xml
+
+# Directories containing the source code.
+# gtk-doc will search all .c and .h files beneath these paths
+# for inline comments documenting functions and macros.
+# e.g. DOC_SOURCE_DIR=$(top_srcdir)/gtk $(top_srcdir)/gdk
+DOC_SOURCE_DIR=$(top_srcdir)/src
+
+# Extra options to pass to gtkdoc-scangobj. Normally not needed.
+SCANGOBJ_OPTIONS=
+
+# Extra options to supply to gtkdoc-scan.
+# e.g. SCAN_OPTIONS=--deprecated-guards="GTK_DISABLE_DEPRECATED"
+SCAN_OPTIONS=
+
+# Extra options to supply to gtkdoc-mkdb
+# e.g. MKDB_OPTIONS=--xml-mode --output-format=xml
+MKDB_OPTIONS=--xml-mode --output-format=xml
+
+# Extra options to supply to gtkdoc-mkhtml
+MKHTML_OPTIONS=
+
+# Extra options to supply to gtkdoc-fixref. Normally not needed.
+# e.g. FIXXREF_OPTIONS=--extra-dir=../gdk-pixbuf/html --extra-dir=../gdk/html
+FIXXREF_OPTIONS=
+
+# Used for dependencies. The docs will be rebuilt if any of these change.
+# e.g. HFILE_GLOB=$(top_srcdir)/gtk/*.h
+# e.g. CFILE_GLOB=$(top_srcdir)/gtk/*.c
+HFILE_GLOB=$(top_srcdir)/src/*.h
+CFILE_GLOB=$(top_srcdir)/src/*.c
+
+# Extra header to include when scanning, which are not under DOC_SOURCE_DIR
+# e.g. EXTRA_HFILES=$(top_srcdir}/contrib/extra.h
+EXTRA_HFILES=
+
+# Header files or dirs to ignore when scanning. Use base file/dir names
+# e.g. IGNORE_HFILES=gtkdebug.h gtkintl.h private_code
+IGNORE_HFILES=
+
+# Images to copy into HTML directory.
+# e.g. HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png
+HTML_IMAGES=                                                   \
+       $(top_srcdir)/doc/api/gs-example-details.png            \
+       $(top_srcdir)/doc/api/gs-example-installed.png          \
+       $(top_srcdir)/doc/api/gs-example-search.png
+
+# Extra files that are included by $(DOC_MAIN_SGML_FILE).
+# e.g. content_files=running.xml building.xml changes-2.0.xml
+content_files=
+
+# Files where gtk-doc abbrevations (#GtkWidget) are expanded
+# e.g. expand_content_files=running.xml
+expand_content_files=
+
+# CFLAGS and LDFLAGS for compiling gtkdoc-scangobj with your library.
+# Only needed if you are using gtkdoc-scangobj to dynamically query widget
+# signals and properties.
+# e.g. GTKDOC_CFLAGS=-I$(top_srcdir) -I$(top_builddir) $(GTK_DEBUG_FLAGS)
+# e.g. GTKDOC_LIBS=$(top_builddir)/gtk/$(gtktargetlib)
+GTKDOC_CFLAGS=
+GTKDOC_LIBS=                                                   \
+       $(SOUP_LIBS)                                            \
+       $(GLIB_LIBS)                                            \
+       $(POLKIT_LIBS)                                          \
+       $(APPSTREAM_LIBS)                                       \
+       $(GTK_LIBS)                                             \
+       $(top_builddir)/src/gnome_software-gs-app-list.o        \
+       $(top_builddir)/src/gnome_software-gs-app.o             \
+       $(top_builddir)/src/gnome_software-gs-category.o        \
+       $(top_builddir)/src/gnome_software-gs-os-release.o      \
+       $(top_builddir)/src/gnome_software-gs-plugin.o          \
+       $(top_builddir)/src/gnome_software-gs-review.o          \
+       $(top_builddir)/src/gnome_software-gs-utils.o
+
+# This includes the standard gtk-doc make rules, copied by gtkdocize.
+include $(top_srcdir)/gtk-doc.make
+
+# Comment this out if you want 'make check' to test you doc status
+# and run some sanity checks
+#if ENABLE_GTK_DOC
+#TESTS_ENVIRONMENT = \
+#  DOC_MODULE=$(DOC_MODULE) DOC_MAIN_SGML_FILE=$(DOC_MAIN_SGML_FILE) \
+#  SRCDIR=$(abs_srcdir) BUILDDIR=$(abs_builddir)
+#TESTS = $(GTKDOC_CHECK)
+#endif
+
+CLEANFILES=                                            \
+       gnome-software.args                             \
+       gnome-software.hierarchy                        \
+       gnome-software.interfaces                       \
+       gnome-software.prerequisites                    \
+       gnome-software.signals                          \
+       gnome-software-*.txt                            \
+       *.stamp
+
+-include $(top_srcdir)/git.mk
diff --git a/doc/api/gnome-software-docs.xml b/doc/api/gnome-software-docs.xml
index 06ef6d9..1e111a2 100644
--- a/doc/api/gnome-software-docs.xml
+++ b/doc/api/gnome-software-docs.xml
@@ -613,4 +613,21 @@ gs_plugin_adopt_app (GsPlugin *plugin, GsApp *app)
     </partintro>
   </reference>
 
+  <reference id="api">
+    <partintro>
+      <para>
+          This documentation is auto-generated.
+          If you see any issues, please file bugs.
+      </para>
+    </partintro>
+    <title>GNOME Software Plugin API</title>
+    <xi:include href="xml/gs-app-list.xml"/>
+    <xi:include href="xml/gs-app.xml"/>
+    <xi:include href="xml/gs-os-release.xml"/>
+    <xi:include href="xml/gs-plugin.xml"/>
+    <xi:include href="xml/gs-plugin-vfuncs.xml"/>
+    <xi:include href="xml/gs-review.xml"/>
+    <xi:include href="xml/gs-utils.xml"/>
+  </reference>
+
 </book>
diff --git a/doc/update.sh b/doc/update.sh
new file mode 100755
index 0000000..5abf679
--- /dev/null
+++ b/doc/update.sh
@@ -0,0 +1 @@
+scp api/html/* hughsient people freedesktop org:~/public_html/gnome-software
diff --git a/src/gs-plugin-vfuncs.h b/src/gs-plugin-vfuncs.h
index 867c517..57cbfa5 100644
--- a/src/gs-plugin-vfuncs.h
+++ b/src/gs-plugin-vfuncs.h
@@ -19,6 +19,15 @@
  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
  */
 
+
+/**
+ * SECTION:gs-plugin-vfuncs
+ * @title: GsPlugin Exports
+ * @include: gnome-software.h
+ * @stability: Unstable
+ * @short_description: Vfuncs that plugins can implement
+ */
+
 #ifndef __GS_PLUGIN_VFUNCS_H
 #define __GS_PLUGIN_VFUNCS_H
 
diff --git a/src/gs-plugin.c b/src/gs-plugin.c
index 175f263..411e3b1 100644
--- a/src/gs-plugin.c
+++ b/src/gs-plugin.c
@@ -21,7 +21,7 @@
 
 /**
  * SECTION:gs-plugin
- * @title: GsPlugin
+ * @title: GsPlugin Helpers
  * @include: gnome-software.h
  * @stability: Unstable
  * @short_description: Runtime-loaded modules providing functionality