From fbc592133b7d858d3fd61b984e5a9ac5a12b84d0 Mon Sep 17 00:00:00 2001
From: "Pulluri.Shirija" <Pulluri.Shirija@in.bosch.com>
Date: Tue, 21 Feb 2023 12:41:41 +0000
Subject: [PATCH] Update documentation and build it with GTK-doc
Signed-off-by: Pulluri.Shirija <Pulluri.Shirija@in.bosch.com>
---
Makefile.am | 2 +-
README | 2 +-
autogen.sh | 4 ++++
configure.ac | 5 ++++-
debian/changelog | 6 ++++++
debian/control | 3 +--
debian/newport-doc.install | 1 +
debian/newport-doc.links | 1 -
debian/not-installed | 1 +
debian/rules | 9 +++++---
docs/Makefile.am | 42 ++++++++++++++++++++++++++++++++++----
docs/gi-index.xml | 11 ++++++++++
docs/newport-docs.sgml | 30 +++++++++++++++++++++++++++
docs/newport-sections.txt | 5 +++++
interface/Makefile.am | 2 +-
src/newport.c | 10 +++++++++
16 files changed, 120 insertions(+), 14 deletions(-)
create mode 100644 debian/newport-doc.install
delete mode 100644 debian/newport-doc.links
create mode 100644 debian/not-installed
create mode 100644 docs/gi-index.xml
create mode 100644 docs/newport-docs.sgml
create mode 100644 docs/newport-sections.txt
diff --git a/Makefile.am b/Makefile.am
index 7bd493b..1bf169b 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -2,7 +2,7 @@ ACLOCAL_AMFLAGS = -I m4 ${ACLOCAL_FLAGS}
PACKAGE = newport
-SUBDIRS = interface src scripts tests
+SUBDIRS = interface src scripts docs tests
DIST_SUBDIRS = $(SUBDIRS)
pkgconfigdir = $(libdir)/pkgconfig
diff --git a/README b/README
index c93ef50..617a5cf 100644
--- a/README
+++ b/README
@@ -1,6 +1,6 @@
1 Introduction
- Newport is download manager capable of downloading files from the internet for local storage.
+ Newport is a download manager capable of downloading files from the internet for local storage.
Currently the download manager does not specify the type of files that could be downloaded for the automotive system.
The files could be, audio, video, applications, map data, system images etc.
It uses sqlite db to store and retrieve the download links.
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 e025e53..00c35ce 100644
--- a/configure.ac
+++ b/configure.ac
@@ -123,15 +123,18 @@ interface/Makefile
src/Makefile
tests/Makefile
scripts/Makefile
+docs/Makefile
])
+GTK_DOC_CHECK(1.0)
+
AC_OUTPUT
dnl Summary
echo "
newport
--------------
- 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 b5d6dfd..01ebf0f 100644
--- a/debian/changelog
+++ b/debian/changelog
@@ -1,3 +1,9 @@
+newport (0.2024.0co1) apertis; urgency=medium
+
+ * doc: Update documentation and build it with GTK-doc
+
+ -- Pulluri Shirija <Pulluri.Shirija@in.bosch.com> Tue, 21 Feb 2023 18:15:03 +0530
+
newport (0.2023.0+apertis1) apertis; urgency=medium
* Add debian/apertis/lintian
diff --git a/debian/control b/debian/control
index 81146a8..27b0257 100644
--- a/debian/control
+++ b/debian/control
@@ -6,8 +6,8 @@ Build-Depends:
autoconf-archive,
autotools-dev,
debhelper (>= 10),
- dh-apparmor,
gobject-introspection (>= 1.30),
+ gtk-doc-tools,
libcurl4-nss-dev | libcurl-dev,
libgirepository1.0-dev (>= 1.30),
libglib2.0-dev,
@@ -46,7 +46,6 @@ Description: Download manager service - shared library
Package: newport
Architecture: any
Depends:
- apparmor (>= 2.11.0-2ubuntu5~),
libglib2.0-bin,
libnewportiface0 (= ${binary:Version}),
${misc:Depends},
diff --git a/debian/newport-doc.install b/debian/newport-doc.install
new file mode 100644
index 0000000..a39b18f
--- /dev/null
+++ b/debian/newport-doc.install
@@ -0,0 +1 @@
+docs/html/* usr/share/gtk-doc/html/newport
diff --git a/debian/newport-doc.links b/debian/newport-doc.links
deleted file mode 100644
index 07ab604..0000000
--- a/debian/newport-doc.links
+++ /dev/null
@@ -1 +0,0 @@
-usr/share/doc/newport/newport usr/share/doc/newport-doc/html
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/rules b/debian/rules
index 1468ed5..1bcfe24 100755
--- a/debian/rules
+++ b/debian/rules
@@ -8,11 +8,16 @@ include /usr/share/dpkg/default.mk
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-documentation \
+ --enable-gtk-doc \
--enable-installed-tests=yes \
--libexecdir='$${prefix}/lib' \
$(NULL)
@@ -25,8 +30,6 @@ override_dh_install:
rm -f debian/tmp/usr/lib/*/*.la
# fail if anything else is missed
dh_install --fail-missing
- dh_apparmor -pnewport --profile-name=usr.bin.newport
- dh_apparmor -pnewport-tests --profile-name=usr.libexec.installed-tests.newport-0.newport-client
# If this is a release, do extra checks
ifeq ($(filter UNRELEASED,$(DEB_DISTRIBUTION)),)
diff --git a/docs/Makefile.am b/docs/Makefile.am
index b7fae3b..023be16 100644
--- a/docs/Makefile.am
+++ b/docs/Makefile.am
@@ -1,7 +1,41 @@
-if ENABLE_DOCUMENTATION
-SUBDIRS = reference
-else
-SUBDIRS = $(NULL)
+DOC_MODULE = newport
+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=newport
+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..4e0ee96
--- /dev/null
+++ b/docs/gi-index.xml
@@ -0,0 +1,11 @@
+<section xml:id="api-reference">
+ <title>API reference</title>
+ <section xml:id="newport-overview">
+ <title>Newport Overview</title>
+ <para>
+ Mail the maintainers (<email>newport@apertis.org</email>)
+ </para>
+ <para>
+ Newport is download manager capable of downloading files from the internet for local storage.
+ </para>
+</section>
diff --git a/docs/newport-docs.sgml b/docs/newport-docs.sgml
new file mode 100644
index 0000000..609ddae
--- /dev/null
+++ b/docs/newport-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>Newport Reference Manual</title>
+ </bookinfo>
+
+ <chapter>
+ <title>Newport APIs</title>
+ <xi:include href="dbus-org.apertis.Newport.Download.xml"/>
+ <xi:include href="dbus-org.apertis.Newport.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/newport-sections.txt b/docs/newport-sections.txt
new file mode 100644
index 0000000..060ceac
--- /dev/null
+++ b/docs/newport-sections.txt
@@ -0,0 +1,5 @@
+<SECTION>
+<FILE>newport</FILE>
+
+</SECTION>
+
diff --git a/interface/Makefile.am b/interface/Makefile.am
index 984c418..02770d8 100644
--- a/interface/Makefile.am
+++ b/interface/Makefile.am
@@ -26,7 +26,7 @@ service_ldflags = \
$(ERROR_LDFLAGS) \
$(AM_LDFLAGS)
service_codegen_flags = \
- --generate-docbook docs \
+ --generate-docbook $(top_builddir)/docs/dbus \
--c-namespace=Newport \
--c-generate-autocleanup=all \
--interface-prefix=org.apertis.Newport \
diff --git a/src/newport.c b/src/newport.c
index 00f0709..272f3c3 100644
--- a/src/newport.c
+++ b/src/newport.c
@@ -10,6 +10,16 @@
#include "newport-internal.h"
+/**
+ * SECTION:newport
+ * @title: Newport
+ * @short_description: Newport is a download manager capable of downloading files from the internet for local storage.
+ *
+ * Newport is a download manager capable of downloading files from the internet for local storage.
+ * Currently the download manager does not specify the type of files that could be downloaded for the automotive system.
+ * The files could be, audio, video, applications, map data, system images etc.
+ * It uses sqlite db to store and retrieve the download links.
+*/
static gboolean move_file_to_actual_location(DownloadUrlInfo *pUrlInfo,GError **error);
static void download_queued_urls(void);
--
GitLab