doc: Add gtk-doc for new library

2015-04-08 17:20:50 -04:00 · 2015-04-08 17:20:50 -04:00 · de47c23450
commit de47c23450
parent 8a5730525e
9 changed files with 205 additions and 1 deletions
--- a/Makefile.am
+++ b/Makefile.am
@ -17,6 +17,12 @@

 include Makefile-decls.am

+SUBDIRS += .
+
+if ENABLE_GTK_DOC
+SUBDIRS += doc
+endif
+
 privdatadir=$(pkglibdir)

 ACLOCAL_AMFLAGS += -I m4 ${ACLOCAL_FLAGS}
--- a/autogen.sh
+++ b/autogen.sh
@ -15,6 +15,18 @@ fi

 mkdir -p m4

+GTKDOCIZE=$(which gtkdocize 2>/dev/null)
+if test -z $GTKDOCIZE; then
+        echo "You don't have gtk-doc installed, and thus won't be able to generate the documentation."
+        rm -f gtk-doc.make
+        cat > gtk-doc.make <<EOF
+EXTRA_DIST =
+CLEANFILES =
+EOF
+else
+        gtkdocize || exit $?
+fi
+
 if ! test -f libglnx/README.md; then
    git submodule update --init
 fi
--- a/configure.ac
+++ b/configure.ac
@ -68,6 +68,8 @@ m4_ifdef([GOBJECT_INTROSPECTION_CHECK], [
 ])
 AM_CONDITIONAL(BUILDOPT_INTROSPECTION, test "x$found_introspection" = xyes)

+GTK_DOC_CHECK([1.15], [--flavour no-tmpl])
+
 AC_ARG_ENABLE(installed_tests,
              AS_HELP_STRING([--enable-installed-tests],
                             [Install test programs (default: no)]),,
@ -94,6 +96,7 @@ if test x$enable_compose_tooling != xno; then RPM_OSTREE_FEATURES="$RPM_OSTREE_F

 AC_CONFIG_FILES([
 Makefile
+doc/Makefile
 src/lib/rpm-ostree-1.pc
 ])
 AC_OUTPUT
@ -103,4 +106,5 @@ echo "

    usrbinatomic:	$enable_usrbinatomic
    compose tooling:	$enable_compose_tooling
+    gtk-doc:            $enable_gtk_doc
 "
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@ -0,0 +1,103 @@
+# Copyright (C) 2013 Colin Walters <walters@verbum.org>
+#
+# This library is free software; you can redistribute it and/or
+# modify it under the terms of the GNU Lesser General Public
+# License as published by the Free Software Foundation; either
+# version 2 of the License, or (at your option) any later version.
+#
+# This library is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+# Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public
+# License along with this library; if not, write to the
+# Free Software Foundation, Inc., 59 Temple Place - Suite 330,
+# Boston, MA 02111-1307, USA.
+
+abs_top_builddir = @abs_top_builddir@
+
+include ../Makefile-lib-defines.am
+
+NULL =
+
+# We require automake 1.6 at least.
+AUTOMAKE_OPTIONS = 1.6
+
+# The name of the module, e.g. 'glib'.
+DOC_MODULE=rpmostree
+
+# The top-level SGML file. You can change this if you want to.
+DOC_MAIN_SGML_FILE=$(DOC_MODULE)-docs.xml
+
+# The directory containing the source code. Relative to $(srcdir).
+# gtk-doc will search all .c & .h files beneath here for inline comments
+# documenting the functions and macros.
+# e.g. DOC_SOURCE_DIR=../../../gtk
+DOC_SOURCE_DIR=$(top_srcdir)/src/lib
+
+# Extra options to pass to gtkdoc-scangobj. Not normally needed.
+SCANGOBJ_OPTIONS= --version
+
+# Extra options to supply to gtkdoc-scan.
+# e.g. SCAN_OPTIONS=--deprecated-guards="GTK_DISABLE_DEPRECATED"
+SCAN_OPTIONS= --rebuild-types
+
+# Extra options to supply to gtkdoc-mkdb.
+# e.g. MKDB_OPTIONS=--sgml-mode --output-format=xml
+MKDB_OPTIONS=--sgml-mode --output-format=xml
+
+# Extra options to supply to gtkdoc-mktmpl
+# e.g. MKTMPL_OPTIONS=--only-section-tmpl
+MKTMPL_OPTIONS=
+
+# MKHTML_OPTIONS=--path="$(builddir)/html $(srcdir)/html"
+
+# Extra options to supply to gtkdoc-fixref. Not normally 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=$(addprefix $(top_srcdir)/,$(librpmostree_public_headers))
+CFILE_GLOB=$(top_srcdir)/src/lib/*.c
+
+# Header files to ignore when scanning.
+# e.g. IGNORE_HFILES=gtkdebug.h gtkintl.h
+IGNORE_HFILES= \
+	$(NULL)
+
+# Images to copy into HTML directory.
+# e.g. HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png
+HTML_IMAGES=
+
+# Extra SGML files that are included by $(DOC_MAIN_SGML_FILE).
+# e.g. content_files=running.sgml building.sgml changes-2.0.sgml
+content_files= \
+	overview.xml \
+	$(NULL)
+
+# SGML files where gtk-doc abbrevations (#GtkWidget) are expanded
+# These files must be listed here *and* in content_files
+# e.g. expand_content_files=running.sgml
+expand_content_files= \
+	version.xml \
+	$(NULL)
+
+# 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. INCLUDES=-I$(top_srcdir) -I$(top_builddir) $(GTK_DEBUG_FLAGS)
+# e.g. GTKDOC_LIBS=$(top_builddir)/gtk/$(gtktargetlib)
+GTKDOC_LIBS=
+
+# Hacks around gtk-doc brokenness for out of tree builds
+rpmostree-sections.txt: $(srcdir)/rpmostree-sections.txt
+	cp $< $@
+
+version.xml:
+	echo -n $(VERSION) > "$@"
+
+# This includes the standard gtk-doc make rules, copied by gtkdocize.
+include $(top_srcdir)/gtk-doc.make
--- a/doc/overview.xml
+++ b/doc/overview.xml
@ -0,0 +1,18 @@
+<?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">
+]>
+<part id="overview">
+  <title>rpm-ostree Overview</title>
+  <chapter id="rpmostree-intro">
+    <title>Introduction</title>
+    <para>
+      The project aims to bring together a hybrid of image-like upgrade
+      features (reliable replication, atomicity), with package-like
+      flexibility (seeing package sets inside trees, layering, partial live
+      updates).  For more information, see the <literal>README.md</literal>
+      in the upstream project.  This manual covers the gtk-doc.
+    </para>
+  </chapter>
+</part>
--- a/doc/rpmostree-docs.xml
+++ b/doc/rpmostree-docs.xml
@ -0,0 +1,24 @@
+<?xml version="1.0"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+               "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"
+[
+  <!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'">
+  <!ENTITY version SYSTEM "version.xml">
+]>
+<book id="index">
+	<bookinfo>
+		<title>rpm-ostree Manual</title>
+		<releaseinfo>for &version;</releaseinfo>
+	</bookinfo>
+
+	<chapter xml:id="reference">
+		<title>API Reference</title>
+		<xi:include href="xml/librpmostree-dbquery.xml"/>
+
+		<index id="api-index-full">
+			<title>API Index</title>
+			<xi:include href="xml/api-index-full.xml"><xi:fallback /></xi:include>
+		</index>
+
+	</chapter>
+</book>
--- a/doc/rpmostree-sections.txt
+++ b/doc/rpmostree-sections.txt
@ -0,0 +1,9 @@
+<SECTION>
+<FILE>librpmostree-dbquery</FILE>
+RpmOstreeDbQueryResult
+rpm_ostree_db_query_result_get_type
+rpm_ostree_db_query_result_get_packages
+rpm_ostree_db_query_ref
+rpm_ostree_db_query_unref
+rpm_ostree_db_query
+</SECTION>
--- a/packaging/rpm-ostree.spec.in
+++ b/packaging/rpm-ostree.spec.in
@ -25,16 +25,25 @@ Requires: /usr/bin/yum
 This tool takes a set of packages, and commits them to an OSTree
 repository.  At the moment, it is intended for use on build servers.

+%package devel
+Summary: Development headers for %{name}
+Group: Development/Libraries
+Requires: %{name} = %{version}-%{release}
+
+%description devel
+The %{name}-devel package includes the header files for the %{name} library.
+
 %prep
 %setup -q -n %{name}-%{version}

 %build
 env NOCONFIGURE=1 ./autogen.sh
-%configure --disable-silent-rules --enable-patched-hawkey-and-libsolv --enable-usrbinatomic
+%configure --disable-silent-rules --enable-gtk-doc --enable-patched-hawkey-and-libsolv --enable-usrbinatomic
 make %{?_smp_mflags}

 %install
 make install DESTDIR=$RPM_BUILD_ROOT INSTALL="install -p -c"
+find $RPM_BUILD_ROOT -name '*.la' -delete

 %files
 %doc COPYING README.md
@ -42,6 +51,16 @@ make install DESTDIR=$RPM_BUILD_ROOT INSTALL="install -p -c"
 %{_bindir}/rpm-ostree
 %{_libdir}/%{name}/
 %{_mandir}/man1/*
+%{_libdir}/*.so.1*
+%{_libdir}/girepository-1.0/*.typelib
+
+%files devel
+%{_libdir}/lib*.so
+%{_includedir}/*
+%{_libdir}/pkgconfig/*
+%dir %{_datadir}/gtk-doc/html/*
+%{_datadir}/gtk-doc/html/*
+%{_datadir}/gir-1.0/*-1.0.gir

 %changelog
 * Fri Mar 07 2014 Colin Walters <walters@verbum.org> - 2014.5-1
--- a/src/lib/rpmostree-db.c
+++ b/src/lib/rpmostree-db.c
@ -25,6 +25,15 @@
 #include "rpmostree-db.h"
 #include "rpmostree-cleanup.h"

+/**
+ * SECTION:librpmostree-dbquery
+ * @title: Query RPM database
+ * @short_description: Access the RPM database in commits
+ *
+ * These APIs provide queryable access to the RPM database inside an
+ * OSTree repository.
+ */
+
 struct RpmOstreeDbQueryResult 
 {
  volatile gint refcount;