From 7d3b7d1b8d3fe39b239d20ff8743b936077653d0 Mon Sep 17 00:00:00 2001
From: Pulluri Shirija <pulluri.shirija@in.bosch.com>
Date: Wed, 1 Mar 2023 19:09:27 +0000
Subject: [PATCH] Update documentation and build it with GTK-doc
---
Makefile.am | 2 +
autogen.sh | 4 ++
configure.ac | 6 ++-
debian/changelog | 6 +++
debian/control | 1 +
debian/not-installed | 1 +
debian/prestwood-doc.install | 1 +
debian/prestwood-doc.links | 1 -
debian/rules | 6 +++
docs/Makefile.am | 42 +++++++++++++++++++--
docs/gi-index.xml | 11 ++++++
docs/prestwood-docs.sgml | 30 +++++++++++++++
docs/prestwood-sections.txt | 5 +++
interface/Makefile.am | 2 +-
interface/org.apertis.Prestwood.Service.xml | 4 +-
src/prestwood.c | 8 ++++
16 files changed, 120 insertions(+), 10 deletions(-)
create mode 100644 debian/not-installed
create mode 100644 debian/prestwood-doc.install
delete mode 100644 debian/prestwood-doc.links
create mode 100644 docs/gi-index.xml
create mode 100644 docs/prestwood-docs.sgml
create mode 100644 docs/prestwood-sections.txt
diff --git a/Makefile.am b/Makefile.am
index c92cde0..5bf206a 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -5,8 +5,10 @@ PACKAGE = prestwood
SUBDIRS = \
interface \
src \
+ docs \
tests \
$(NULL)
+DIST_SUBDIRS = $(SUBDIRS)
pkgconfigdir = $(libdir)/pkgconfig
pkgconfig_DATA = prestwood.pc
diff --git a/autogen.sh b/autogen.sh
index abadb9a..02e2bb6 100755
--- a/autogen.sh
+++ b/autogen.sh
@@ -23,6 +23,10 @@ if [ "$#" = 0 -a "x$NOCONFIGURE" = "x" ]; then
fi
aclocal --install || exit 1
+
+# Mainly copies the gtk-doc.make file in srcdir
+gtkdocize || exit 1
+
autoreconf --verbose --force --install || exit 1
cd "$olddir"
diff --git a/configure.ac b/configure.ac
index ddf69a4..dcfbd7c 100644
--- a/configure.ac
+++ b/configure.ac
@@ -102,17 +102,19 @@ Makefile
prestwood.pc
interface/Makefile
src/Makefile
-
+docs/Makefile
tests/Makefile
])
+GTK_DOC_CHECK(1.0)
+
AC_OUTPUT
dnl Summary
echo " prestwood
--------------
- documentation : ${enable_documentation}
+ documentation : ${enable_gtk_doc}
code coverage : ${enable_code_coverage}
compiler warings : ${enable_compile_warnings}
Test suite : ${enable_modular_tests}
diff --git a/debian/changelog b/debian/changelog
index cfb6351..094165b 100644
--- a/debian/changelog
+++ b/debian/changelog
@@ -1,3 +1,9 @@
+prestwood (0.2024.0co1) apertis; urgency=medium
+
+ * doc: Update documentation and build it with GTK-doc
+
+ -- Pulluri Shirija <Pulluri.Shirija@in.bosch.com> Fri, 21 Feb 2023 15:20:03 +0530
+
prestwood (0.2022.0+apertis1) apertis; urgency=medium
* Add debian/apertis/lintian
diff --git a/debian/control b/debian/control
index 520ff33..39a5cb2 100644
--- a/debian/control
+++ b/debian/control
@@ -8,6 +8,7 @@ Build-Depends:
debhelper-compat (= 13),
libglib2.0-dev,
libgirepository1.0-dev (>= 1.30),
+ gtk-doc-tools,
gobject-introspection (>= 1.30),
Standards-Version: 3.9.2
diff --git a/debian/not-installed b/debian/not-installed
new file mode 100644
index 0000000..1c19bd9
--- /dev/null
+++ b/debian/not-installed
@@ -0,0 +1 @@
+usr/share/gtk-doc/*
diff --git a/debian/prestwood-doc.install b/debian/prestwood-doc.install
new file mode 100644
index 0000000..364de7e
--- /dev/null
+++ b/debian/prestwood-doc.install
@@ -0,0 +1 @@
+docs/html/* usr/share/gtk-doc/html/prestwood
diff --git a/debian/prestwood-doc.links b/debian/prestwood-doc.links
deleted file mode 100644
index 9bd1411..0000000
--- a/debian/prestwood-doc.links
+++ /dev/null
@@ -1 +0,0 @@
-usr/share/doc/prestwood/prestwood usr/share/doc/prestwood-doc/html
diff --git a/debian/rules b/debian/rules
index 240186e..39e6ea1 100755
--- a/debian/rules
+++ b/debian/rules
@@ -6,10 +6,16 @@
override_dh_autoreconf:
NOCONFIGURE=1 dh_autoreconf ./autogen.sh --
+# gtkdocize is disabled for now in dh-autoreconf, so it needs to be run
+# manually. See https://salsa.debian.org/debian/dh-autoreconf/-/commit/9f66b177dfcb5a757493721c86228afc1f0f8899
+ mkdir -p m4
+ gtkdocize --copy
+ dh_autoreconf
override_dh_auto_configure:
dh_auto_configure \
-- \
+ --enable-gtk-doc \
--libexecdir='$${prefix}/lib' \
$(NULL)
diff --git a/docs/Makefile.am b/docs/Makefile.am
index b7fae3b..8027c1a 100644
--- a/docs/Makefile.am
+++ b/docs/Makefile.am
@@ -1,7 +1,41 @@
-if ENABLE_DOCUMENTATION
-SUBDIRS = reference
-else
-SUBDIRS = $(NULL)
+DOC_MODULE = prestwood
+DOC_MAIN_SGML_FILE = $(DOC_MODULE)-docs.sgml
+DOC_SOURCE_DIR = \
+ $(top_srcdir)/src
+SCAN_OPTIONS = \
+ --ignore-headers $(top_srcdir)/src/*-internal.h
+MKDB_OPTIONS = \
+ --name-space=prestwood
+HFILE_GLOB = \
+ $(top_srcdir)/src/*.h
+CFILE_GLOB = \
+ $(top_srcdir)/src/*.c
+AM_CPPFLAGS = \
+ -I$(top_builddir) \
+ -I$(top_srcdir) \
+ -I$(top_srcdir)/src
+AM_CFLAGS = $(GLIB_CFLAGS)
+GTKDOC_LIBS = \
+ $(top_builddir) \
+ $(GLIB_LIBS)
+
+# Extra files that are included by $(DOC_MAIN_SGML_FILE).
+# e.g. content_files=running.xml building.xml changes-2.0.xml
+content_files=gi-index.xml
+
+# Files where gtk-doc abbreviations (#GtkWidget) are expanded
+# e.g. expand_content_files=running.xml
+expand_content_files=
+
+# This includes the standard gtk-doc make rules, copied by gtkdocize.
+include $(top_srcdir)/gtk-doc.make
+
+# Let 'make check' test the 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
-include $(top_srcdir)/git.mk
diff --git a/docs/gi-index.xml b/docs/gi-index.xml
new file mode 100644
index 0000000..a30ee8d
--- /dev/null
+++ b/docs/gi-index.xml
@@ -0,0 +1,11 @@
+<section xml:id="api-reference">
+ <title>API reference</title>
+ <section xml:id="prestwood-overview">
+ <title>Prestwood Overview</title>
+ <para>
+ Mail the maintainers (<email>prestwood@apertis.org</email>)
+ </para>
+ <para>
+ Prestwood is a service responsible for maintaining the mount points list.
+ </para>
+</section>
diff --git a/docs/prestwood-docs.sgml b/docs/prestwood-docs.sgml
new file mode 100644
index 0000000..879187d
--- /dev/null
+++ b/docs/prestwood-docs.sgml
@@ -0,0 +1,30 @@
+<?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 % gtkdocentities SYSTEM "xml/gtkdocentities.ent">
+ %gtkdocentities;
+]>
+<book id="index" xmlns:xi="http://www.w3.org/2003/XInclude">
+ <bookinfo>
+ <title>Prestwood Reference Manual</title>
+ </bookinfo>
+
+ <chapter>
+ <title>Prestwood APIs</title>
+ <xi:include href="dbus-org.apertis.Prestwood.Service.xml"/>
+ </chapter>
+ <!-- enable this when you use gobject types
+ <chapter id="object-tree">
+ <title>Object Hierarchy</title>
+ <xi:include href="xml/tree_index.sgml"/>
+ </chapter>
+ -->
+ <xi:include href="xml/api-index-full.xml"><xi:fallback /></xi:include>
+ <xi:include href="xml/api-index-deprecated.xml"><xi:fallback /></xi:include>
+ <!-- enable this when you use gobject introspection annotations
+ <xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>
+ -->
+</book>
+
diff --git a/docs/prestwood-sections.txt b/docs/prestwood-sections.txt
new file mode 100644
index 0000000..ca42207
--- /dev/null
+++ b/docs/prestwood-sections.txt
@@ -0,0 +1,5 @@
+<SECTION>
+<FILE>prestwood</FILE>
+
+</SECTION>
+
diff --git a/interface/Makefile.am b/interface/Makefile.am
index 3ad62d5..2c65603 100644
--- a/interface/Makefile.am
+++ b/interface/Makefile.am
@@ -27,7 +27,7 @@ service_ldflags = \
$(WARN_LDFLAGS) \
$(AM_LDFLAGS)
service_codegen_flags = \
- --generate-docbook docs \
+ --generate-docbook $(top_builddir)/docs/dbus \
--c-namespace=Prestwood \
--interface-prefix=org.apertis.Prestwood \
$(NULL)
diff --git a/interface/org.apertis.Prestwood.Service.xml b/interface/org.apertis.Prestwood.Service.xml
index 4b9db60..47f7c09 100644
--- a/interface/org.apertis.Prestwood.Service.xml
+++ b/interface/org.apertis.Prestwood.Service.xml
@@ -1,11 +1,11 @@
<?xml version="1.0" encoding="UTF-8" ?>
<node name="/" xmlns:doc="http://www.freedesktop.org/dbus/1.0/doc.dtd">
<!--
- Prestwood.Service:
+ org.apertis.Prestwood.Service:
@short_description: Functional Interfaces for the Prestwood Service
@since: 1.0
-Prestwood is a service responsible for maintaining the mount points list.
+ Prestwood is a service responsible for maintaining the mount points list.
-->
<interface name="org.apertis.Prestwood.Service">
diff --git a/src/prestwood.c b/src/prestwood.c
index 0f1ebac..4952753 100644
--- a/src/prestwood.c
+++ b/src/prestwood.c
@@ -17,6 +17,14 @@
#include <stdlib.h>
#include <ctype.h>
+/**
+ * SECTION:prestwood
+ * @title: Prestwood
+ * @short_description: Prestwood is a service responsible for maintaining the mount points list
+ *
+ * Prestwood is a service responsible for maintaining the mount points list
+ */
+
static gboolean gPrestwoodInitialized = FALSE;
static Prestwood *gPrestwood = NULL;
static void unref_data (gpointer data, gpointer userdata);
--
GitLab