From de47c234506ea39e7d3f7081761c28d46f833e6b Mon Sep 17 00:00:00 2001 From: Colin Walters Date: Wed, 8 Apr 2015 17:20:50 -0400 Subject: [PATCH] doc: Add gtk-doc for new library --- Makefile.am | 6 ++ autogen.sh | 12 ++++ configure.ac | 4 ++ doc/Makefile.am | 103 +++++++++++++++++++++++++++++++++++ doc/overview.xml | 18 ++++++ doc/rpmostree-docs.xml | 24 ++++++++ doc/rpmostree-sections.txt | 9 +++ packaging/rpm-ostree.spec.in | 21 ++++++- src/lib/rpmostree-db.c | 9 +++ 9 files changed, 205 insertions(+), 1 deletion(-) create mode 100644 doc/Makefile.am create mode 100644 doc/overview.xml create mode 100644 doc/rpmostree-docs.xml create mode 100644 doc/rpmostree-sections.txt diff --git a/Makefile.am b/Makefile.am index dd0600bb..339c192a 100644 --- 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} diff --git a/autogen.sh b/autogen.sh index 7edfbf7a..f25acafd 100755 --- 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 < +# +# 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 diff --git a/doc/overview.xml b/doc/overview.xml new file mode 100644 index 00000000..caec22a7 --- /dev/null +++ b/doc/overview.xml @@ -0,0 +1,18 @@ + + +]> + + rpm-ostree Overview + + Introduction + + 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 README.md + in the upstream project. This manual covers the gtk-doc. + + + diff --git a/doc/rpmostree-docs.xml b/doc/rpmostree-docs.xml new file mode 100644 index 00000000..05932441 --- /dev/null +++ b/doc/rpmostree-docs.xml @@ -0,0 +1,24 @@ + + + +]> + + + rpm-ostree Manual + for &version; + + + + API Reference + + + + API Index + + + + + diff --git a/doc/rpmostree-sections.txt b/doc/rpmostree-sections.txt new file mode 100644 index 00000000..9e629c68 --- /dev/null +++ b/doc/rpmostree-sections.txt @@ -0,0 +1,9 @@ +
+librpmostree-dbquery +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 +
diff --git a/packaging/rpm-ostree.spec.in b/packaging/rpm-ostree.spec.in index f94f66ef..74de540d 100644 --- 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 - 2014.5-1 diff --git a/src/lib/rpmostree-db.c b/src/lib/rpmostree-db.c index 505936fb..a4a4bbf2 100644 --- 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;