Merge lp:~xnox/ubuntu/raring/libnih/gtkdoc into lp:ubuntu/raring/libnih

[Dimitri John Ledkov]

[Steve Langasek (vorlon)]

> +DISTCHECK_CONFIGURE_FLAGS=--enable-gtk-doc

Can you explain why this is needed? I can't see what this has to do with adding support for gtk-doc.

> -Build-Depends: debhelper (>= 8.1.3~), pkg-config (>= 0.22), libdbus-1-dev (>= 1.4), libexpat1-dev (>= 2.0.0), dbus (>= 1.4), libc6-dev (>= 2.15~) | libc6.1-dev (>= 2.15~)
> +Build-Depends: debhelper (>= 8.1.3~), pkg-config (>= 0.22), libdbus-1-dev (>= 1.4), libexpat1-dev (>= 2.0.0), dbus (>= 1.4), libc6-dev (>= 2.15~) | libc6.1-dev (>= 2.15~), dh-autoreconf

Seems to be missing a build-dependency on gtk-doc-tools, which provides the 'gtkdocize' tool you call in debian/rules.

Would it be possible to trim the dead code out of docs/reference/nih/Makefile.am? It would be easier to read if it weren't full of commented examples of things we're not using. Since this is a locally modified file already, there doesn't seem to be any value in keeping it close to the gtkdoc template.

Can you add information to debian/clean to reverse the effect of gtkdocize in the clean target? (dh-autoreconf's dh sequence already takes care of this for the files that autoreconf creates/modifies.)

review: Needs Fixing

[lp:~xnox/ubuntu/raring/libnih/gtkdoc]

1071. By Dimitri John Ledkov on 2012-12-13

* Undo gtkdocize with debian/clean
* Don't change dist config flags (upstream should do that)
* add gtk-doc-tools build-dep
* Remove boilerplate from copied reference Makefile.am
* "Avoid" in configure.ac build-dep on glib & gobject (we don't need
  gtk-doc signal scanner)

[Dimitri John Ledkov (xnox)]

pushed an update, addressing your comments as well as getting it to build in clean environment.
It's still a bit rough - many gtk-doc warnings & undocumented things & not all code is scanned.
So it will require further tweaking.
Should we have this in the package at all? Or only publish it online somewhere?

[James Hunt (jamesodhunt)]

Hi Dmitrijs,

LP is still showing merge conflicts with your branch...?

> Should we have this in the package at all? Or only publish it online somewhere?
How big is the generated output and in what format(s)? Presumably libnih-dev would be a good place if it isn't huge (and can be compressed).

I appreciate we don't have the ability to action it, but I do think this MP should be raised on lp:libnih first to avoid the Ubuntu package deviating from the upstream.

[Steve Langasek (vorlon)]

Still seeing merge conflicts here. Happy to merge this once that's addressed.

> Should we have this in the package at all? Or only publish it online somewhere?

I think this is reasonable to package up and include in libnih-dev, regardless of size (or a new libnih-doc, if someone objects to the size).

Unmerged revisions

1071. By Dimitri John Ledkov on 2012-12-13

* Undo gtkdocize with debian/clean
* Don't change dist config flags (upstream should do that)
* add gtk-doc-tools build-dep
* Remove boilerplate from copied reference Makefile.am
* "Avoid" in configure.ac build-dep on glib & gobject (we don't need
  gtk-doc signal scanner)

1070. By Dimitri John Ledkov on 2012-12-13

Add gtk-doc documentation for nih.

=== modified file 'Makefile.am'
--- Makefile.am	2010-02-04 22:30:23 +0000
+++ Makefile.am	2012-12-13 23:49:21 +0000
@@ -1,7 +1,8 @@
 ## Process this file with automake to produce Makefile.in
 
-SUBDIRS = m4 intl nih nih-dbus nih-dbus-tool po
+SUBDIRS = m4 intl nih nih-dbus nih-dbus-tool po docs/reference/nih
 
 EXTRA_DIST = HACKING
 
 ACLOCAL_AMFLAGS = --install -I m4
+

=== modified file 'configure.ac'
--- configure.ac	2010-12-23 22:08:49 +0000
+++ configure.ac	2012-12-13 23:49:21 +0000
@@ -58,10 +58,21 @@
 	      AC_SUBST([NIH_DBUS_TOOL], ["\${top_builddir}/nih-dbus-tool/nih-dbus-tool"])])],
       [AC_SUBST([NIH_DBUS_TOOL], ["\${top_builddir}/nih-dbus-tool/nih-dbus-tool"])])
 
+# check for gtk-doc
+m4_ifdef([GTK_DOC_CHECK], [
+_PACKAGE_NAME=$PACKAGE_NAME
+PACKAGE_NAME="glib"
+GTK_DOC_CHECK([1.14],[--flavour no-tmpl])
+PACKAGE_NAME=_PACKAGE_NAME
+],[
+AM_CONDITIONAL([ENABLE_GTK_DOC], false)
+])
+
 AC_CONFIG_FILES([ Makefile m4/Makefile intl/Makefile
 		  nih/Makefile nih/libnih.pc
 		  nih-dbus/Makefile nih-dbus/libnih-dbus.pc
 		  nih-dbus-tool/Makefile
+		  docs/reference/nih/Makefile
 		  po/Makefile.in ])
 AC_CONFIG_HEADERS([config.h])
 AC_OUTPUT

=== modified file 'debian/changelog'
--- debian/changelog	2012-12-13 15:00:30 +0000
+++ debian/changelog	2012-12-13 23:49:21 +0000
@@ -1,3 +1,4 @@
+<<<<<<< TREE
 libnih (1.0.3-4ubuntu14) raring; urgency=low
 
   * Update dbus code generator to allow for empty lists for type 'as'.
@@ -6,6 +7,14 @@
 
  -- Stéphane Graber <[e-mail]>  Thu, 13 Dec 2012 10:00:27 -0500
 
+=======
+libnih (1.0.3-4ubuntu14) UNRELEASED; urgency=low
+
+  * Add gtk-doc documentation for nih.
+
+ -- Dmitrijs Ledkovs <[e-mail]>  Thu, 13 Dec 2012 00:27:35 +0000
+
+>>>>>>> MERGE-SOURCE
 libnih (1.0.3-4ubuntu13) raring; urgency=low
 
   [ Petr Lautrbach <[e-mail]>, Dmitrijs Ledkovs ]

=== added file 'debian/clean'
--- debian/clean	1970-01-01 00:00:00 +0000
+++ debian/clean	2012-12-13 23:49:21 +0000
@@ -0,0 +1,2 @@
+m4/gtk-doc.m4
+gtk-doc.make
\ No newline at end of file

=== modified file 'debian/control'
--- debian/control	2012-02-16 06:57:48 +0000
+++ debian/control	2012-12-13 23:49:21 +0000
@@ -4,7 +4,7 @@
 Maintainer: Ubuntu Developers <[e-mail]>
 XSBC-Original-Maintainer: Scott James Remnant <[e-mail]>
 Standards-Version: 3.9.1
-Build-Depends: debhelper (>= 8.1.3~), pkg-config (>= 0.22), libdbus-1-dev (>= 1.4), libexpat1-dev (>= 2.0.0), dbus (>= 1.4), libc6-dev (>= 2.15~) | libc6.1-dev (>= 2.15~)
+Build-Depends: debhelper (>= 8.1.3~), pkg-config (>= 0.22), libdbus-1-dev (>= 1.4), libexpat1-dev (>= 2.0.0), dbus (>= 1.4), libc6-dev (>= 2.15~) | libc6.1-dev (>= 2.15~), dh-autoreconf, gtk-doc-tools
 Vcs-Git: git://git.debian.org/git/collab-maint/libnih.git
 Vcs-Browser: http://git.debian.org/?p=collab-maint/libnih.git;a=summary
 Homepage: https://launchpad.net/libnih
@@ -14,8 +14,8 @@
 Pre-Depends: ${misc:Pre-Depends}, ${shlibs:Depends}, ${misc:Depends}
 Multi-Arch: same
 Description: NIH Utility Library
- libnih is a light-weight "standard library" of C functions to ease the
- development of other libraries and applications, especially those
+ libnih is a light-weight "standard library" of C functions to ease
+ the development of other libraries and applications, especially those
  normally found in /lib.
  .
  This package contains the shared library.
@@ -73,3 +73,15 @@
  remote objects easier.
  .
  The generated code requires libnih-dbus-dev to be compiled.
+
+Package: libnih-doc
+Priority: optional
+Section: doc
+Architecture: all
+Depends: ${shlibs:Depends}, ${misc:Depends}
+Description: NIH Utility Library (API reference)
+ libnih is a light-weight "standard library" of C functions to ease the
+ development of other libraries and applications, especially those
+ normally found in /lib.
+ .
+ This package contains the API reference documentation.

=== added file 'debian/libnih-doc.doc-base.nih'
--- debian/libnih-doc.doc-base.nih	1970-01-01 00:00:00 +0000
+++ debian/libnih-doc.doc-base.nih	2012-12-13 23:49:21 +0000
@@ -0,0 +1,11 @@
+Document: nih
+Title: NIH Utility Library Reference Manual
+Author: Scott James Remnant
+Abstract: libnih is a light-weight "standard library" of C functions to ease
+ the development of other libraries and applications, especially those
+ normally found in /lib.
+Section: Programming/C
+
+Format: HTML
+Index: /usr/share/doc/libnih-doc/nih/index.html
+Files: /usr/share/doc/libnih-doc/nih/*.html

=== added file 'debian/libnih-doc.install'
--- debian/libnih-doc.install	1970-01-01 00:00:00 +0000
+++ debian/libnih-doc.install	2012-12-13 23:49:21 +0000
@@ -0,0 +1,2 @@
+usr/share/gtk-doc/html/* usr/share/doc/libnih-doc
+

=== added file 'debian/libnih-doc.links'
--- debian/libnih-doc.links	1970-01-01 00:00:00 +0000
+++ debian/libnih-doc.links	2012-12-13 23:49:21 +0000
@@ -0,0 +1,2 @@
+usr/share/doc/libnih-doc/nih usr/share/gtk-doc/html/nih
+

=== modified file 'debian/rules'
--- debian/rules	2012-02-08 23:43:21 +0000
+++ debian/rules	2012-12-13 23:49:21 +0000
@@ -1,6 +1,6 @@
 #!/usr/bin/make -f
 %:
-	dh $@
+	dh $@ --with autoreconf --parallel
 
 
 CFLAGS := -Wall -fstack-protector -fPIE $(shell dpkg-buildflags --get CFLAGS)
@@ -8,9 +8,14 @@
 
 DEB_HOST_MULTIARCH ?= $(shell dpkg-architecture -qDEB_HOST_MULTIARCH)
 
+override_dh_autoreconf:
+	gtkdocize
+	dh_autoreconf
+
 override_dh_auto_configure:
 	dh_auto_configure -- CFLAGS="$(CFLAGS)" LDFLAGS="$(LDFLAGS)" \
-		--libdir=/lib/$(DEB_HOST_MULTIARCH)
+		--libdir=/lib/$(DEB_HOST_MULTIARCH) \
+		--enable-gtk-doc
 
 override_dh_auto_install:
 	dh_auto_install -- pkgconfigdir=\$${prefix}/lib/$(DEB_HOST_MULTIARCH)/pkgconfig

=== added directory 'docs'
=== added directory 'docs/reference'
=== added directory 'docs/reference/nih'
=== added file 'docs/reference/nih/Makefile.am'
--- docs/reference/nih/Makefile.am	1970-01-01 00:00:00 +0000
+++ docs/reference/nih/Makefile.am	2012-12-13 23:49:21 +0000
@@ -0,0 +1,23 @@
+## Taken from gtk-doc/examples/Makefile.am
+DOC_MODULE=nih
+DOC_MODULE_VERSION=$(VERSION)
+DOC_MAIN_SGML_FILE=$(DOC_MODULE)-docs.sgml
+DOC_SOURCE_DIR=$(top_srcdir)/nih
+HFILE_GLOB=$(top_srcdir)/nih/*.h
+CFILE_GLOB=$(top_srcdir)/nih/*.c
+
+AUTOMAKE_OPTIONS = 1.6
+MKDB_OPTIONS=--xml-mode --output-format=xml
+
+# This includes the standard gtk-doc make rules, copied by gtkdocize.
+include $(top_srcdir)/gtk-doc.make
+
+if ENABLE_GTK_DOC
+TESTS_ENVIRONMENT = cd $(srcdir) && \
+  DOC_MODULE=$(DOC_MODULE) DOC_MAIN_SGML_FILE=$(DOC_MAIN_SGML_FILE) \
+  SRCDIR=$(abs_srcdir) BUILDDIR=$(abs_builddir)
+#TESTS = $(GTKDOC_CHECK)
+# gtkdoc-check currently fails...
+check-local:
+	-$(TESTS_ENVIRONMENT) $(GTKDOC_CHECK)
+endif

=== added file 'docs/reference/nih/nih-docs.sgml'
--- docs/reference/nih/nih-docs.sgml	1970-01-01 00:00:00 +0000
+++ docs/reference/nih/nih-docs.sgml	2012-12-13 23:49:21 +0000
@@ -0,0 +1,63 @@
+<?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'">
+]>
+<book id="index">
+  <bookinfo>
+    <title>nih Reference Manual</title>
+    <releaseinfo>
+      for nih 1.0.
+      The latest version of this documentation can be found on-line at
+      <ulink role="online-location" url="http://[SERVER]/nih/index.html">http://[SERVER]/nih/</ulink>.
+    </releaseinfo>
+  </bookinfo>
+
+  <chapter>
+    <title>NIH Utility Library</title>
+        <xi:include href="xml/alloc.xml"/>
+    <xi:include href="xml/child.xml"/>
+    <xi:include href="xml/command.xml"/>
+    <xi:include href="xml/config.xml"/>
+    <xi:include href="xml/error.xml"/>
+    <xi:include href="xml/errors.xml"/>
+    <xi:include href="xml/file.xml"/>
+    <xi:include href="xml/hash.xml"/>
+    <xi:include href="xml/io.xml"/>
+    <xi:include href="xml/list.xml"/>
+    <xi:include href="xml/logging.xml"/>
+    <xi:include href="xml/macros.xml"/>
+    <xi:include href="xml/main.xml"/>
+    <xi:include href="xml/option.xml"/>
+    <xi:include href="xml/signal.xml"/>
+    <xi:include href="xml/string.xml"/>
+    <xi:include href="xml/test.xml"/>
+    <xi:include href="xml/test_alloc.xml"/>
+    <xi:include href="xml/test_divert.xml"/>
+    <xi:include href="xml/test_files.xml"/>
+    <xi:include href="xml/test_hash.xml"/>
+    <xi:include href="xml/test_list.xml"/>
+    <xi:include href="xml/test_output.xml"/>
+    <xi:include href="xml/test_process.xml"/>
+    <xi:include href="xml/test_values.xml"/>
+    <xi:include href="xml/timer.xml"/>
+    <xi:include href="xml/tree.xml"/>
+    <xi:include href="xml/watch.xml"/>
+
+  </chapter>
+  <chapter id="object-tree">
+    <title>Object Hierarchy</title>
+     <xi:include href="xml/tree_index.sgml"/>
+  </chapter>
+  <index id="api-index-full">
+    <title>API Index</title>
+    <xi:include href="xml/api-index-full.xml"><xi:fallback /></xi:include>
+  </index>
+  <index id="deprecated-api-index" role="deprecated">
+    <title>Index of deprecated API</title>
+    <xi:include href="xml/api-index-deprecated.xml"><xi:fallback /></xi:include>
+  </index>
+
+  <xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>
+</book>