From f2b17fded50efc4f9bbd510cdc4f599f6993f1ed Mon Sep 17 00:00:00 2001 From: Dieter Verfaillie Date: Thu, 15 Nov 2012 20:56:21 +0100 Subject: docs: make gtkdoc-mkdb ignore cmph doxygen comment blocks. When building g-i reference documentation, girepository/cmph/* was being scanned for GTK-Doc comment blocks by gtkdoc-mkdb. Unfortunately, cmph uses doxygen comment blocks which also start with /**. This patch prevents gtkdoc-mkdb from complaining. https://bugzilla.gnome.org/show_bug.cgi?id=688418 --- docs/reference/Makefile.am | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/reference/Makefile.am') diff --git a/docs/reference/Makefile.am b/docs/reference/Makefile.am index 19c9affa..c3157be3 100644 --- a/docs/reference/Makefile.am +++ b/docs/reference/Makefile.am @@ -13,7 +13,7 @@ DOC_SOURCE_DIR=$(top_srcdir)/girepository SCAN_OPTIONS= # Extra options to supply to gtkdoc-mkdb -MKDB_OPTIONS=--sgml-mode --output-format=xml --name-space=g +MKDB_OPTIONS=--sgml-mode --output-format=xml --name-space=g --ignore-files=cmph # Used for dependencies HFILE_GLOB=$(top_srcdir)/girepository/*.h -- cgit v1.2.1 From 4789682da92b098359dc3a5f340bee6f7310407d Mon Sep 17 00:00:00 2001 From: Dieter Verfaillie Date: Wed, 21 Aug 2013 12:03:25 +0200 Subject: docs: Update Makefile.am --- docs/reference/Makefile.am | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/reference/Makefile.am') diff --git a/docs/reference/Makefile.am b/docs/reference/Makefile.am index c3157be3..65892027 100644 --- a/docs/reference/Makefile.am +++ b/docs/reference/Makefile.am @@ -28,7 +28,7 @@ IGNORE_HFILES= \ girwriter.h \ girmodule.h -INCLUDES=$(GIREPO_CFLAGS) -I$(top_srcdir) +AM_CPPFLAGS=$(GIREPO_CFLAGS) -I$(top_srcdir) GTKDOC_LIBS = $(GIREPO_LIBS) $(top_builddir)/libgirepository-1.0.la $(top_builddir)/libgirepository-internals.la content_files = \ -- cgit v1.2.1 From 9c5c43c01ef4e2f81c4bedb9da613fd5a1dccd82 Mon Sep 17 00:00:00 2001 From: Dieter Verfaillie Date: Fri, 20 Sep 2013 17:51:29 +0200 Subject: girepository: remove glib-compat We depend on glib-2.0 >= 2.36.0, so no need to keep a 2.22.X compatibility symbol around... --- docs/reference/Makefile.am | 1 - 1 file changed, 1 deletion(-) (limited to 'docs/reference/Makefile.am') diff --git a/docs/reference/Makefile.am b/docs/reference/Makefile.am index 65892027..937ac808 100644 --- a/docs/reference/Makefile.am +++ b/docs/reference/Makefile.am @@ -21,7 +21,6 @@ CFILE_GLOB=$(top_srcdir)/girepository/*.c # Headers to ignore IGNORE_HFILES= \ - glib-compat.h \ girnode.h \ ginfo.h \ girparser.h \ -- cgit v1.2.1 From a737daa16e458e87f189c2535f11f4bd2dde8f1a Mon Sep 17 00:00:00 2001 From: Dieter Verfaillie Date: Thu, 10 Oct 2013 22:21:18 +0200 Subject: docs: fix up reference docs a bit - require GTK-Doc 1.19 - remove sgml mode - automatically generate gi.types (needs GTK-Doc 1.19) - fix https://bugzilla.gnome.org/show_bug.cgi?id=700025 [WIP] - rearange sections a bit [WIP] - add gi-building, gi-programming sections [WIP] - mark missing docs with TODO, which is only marginaly better than nothing but at least can be grepped :) https://bugzilla.gnome.org/show_bug.cgi?id=571648 --- docs/reference/Makefile.am | 142 ++++++++++++++++++++++++++++++++------------- 1 file changed, 101 insertions(+), 41 deletions(-) (limited to 'docs/reference/Makefile.am') diff --git a/docs/reference/Makefile.am b/docs/reference/Makefile.am index 937ac808..d3b3f930 100644 --- a/docs/reference/Makefile.am +++ b/docs/reference/Makefile.am @@ -1,61 +1,121 @@ AUTOMAKE_OPTIONS = 1.6 -# The name of the module. +# The name of the module, e.g. 'glib'. DOC_MODULE=gi -# The top-level SGML file. -DOC_MAIN_SGML_FILE=gi-docs.sgml +# Uncomment for versioned docs and specify the version of the module, e.g. '2'. +#DOC_MODULE_VERSION=2 -# The directory containing the source code. Relative to $(srcdir) +# The top-level XML file (SGML in the past). You can change this if you want to. +DOC_MAIN_SGML_FILE=gi-docs.xml + +# Directories containing the source code. +# gtk-doc will search all .c and .h files beneath these paths +# for inline comments documenting functions and macros. +# e.g. DOC_SOURCE_DIR=$(top_srcdir)/gtk $(top_srcdir)/gdk DOC_SOURCE_DIR=$(top_srcdir)/girepository -# Extra options to supply to gtkdoc-scan -SCAN_OPTIONS= +# Extra options to pass to gtkdoc-scangobj. Not normally needed. +SCANGOBJ_OPTIONS= -# Extra options to supply to gtkdoc-mkdb -MKDB_OPTIONS=--sgml-mode --output-format=xml --name-space=g --ignore-files=cmph +# Extra options to supply to gtkdoc-scan. +# e.g. SCAN_OPTIONS=--deprecated-guards="GTK_DISABLE_DEPRECATED" +SCAN_OPTIONS=--rebuild-types -# Used for dependencies -HFILE_GLOB=$(top_srcdir)/girepository/*.h -CFILE_GLOB=$(top_srcdir)/girepository/*.c +# Extra options to supply to gtkdoc-mkdb. +# e.g. MKDB_OPTIONS=--xml-mode --output-format=xml +MKDB_OPTIONS=--xml-mode --output-format=xml --name-space=g --ignore-files=cmph -# Headers to ignore -IGNORE_HFILES= \ - girnode.h \ - ginfo.h \ - girparser.h \ - girwriter.h \ - girmodule.h +# Extra options to supply to gtkdoc-mktmpl +# e.g. MKTMPL_OPTIONS=--only-section-tmpl +MKTMPL_OPTIONS= -AM_CPPFLAGS=$(GIREPO_CFLAGS) -I$(top_srcdir) -GTKDOC_LIBS = $(GIREPO_LIBS) $(top_builddir)/libgirepository-1.0.la $(top_builddir)/libgirepository-internals.la +# Extra options to supply to gtkdoc-mkhtml +MKHTML_OPTIONS= -content_files = \ - gi-gir-reference.xml \ - gi-gir.sgml \ - gi-overview.xml \ - gi-struct-hierarchy.xml +# 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=$(top_srcdir)/girepository/*.h +CFILE_GLOB=$(top_srcdir)/girepository/*.c -HTML_IMAGES = \ +# Extra header to include when scanning, which are not under DOC_SOURCE_DIR +# e.g. EXTRA_HFILES=$(top_srcdir}/contrib/extra.h +EXTRA_HFILES= + +# Header files or dirs to ignore when scanning. Use base file/dir names +# e.g. IGNORE_HFILES=gtkdebug.h gtkintl.h private_code +IGNORE_HFILES= \ + cmph \ + girnode.h \ + girparser.h \ + girwriter.h \ + girmodule.h \ + girepository-private.h + +# Images to copy into HTML directory. +# e.g. HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png +HTML_IMAGES= \ $(srcdir)/images/overview.png -# Extra options to supply to gtkdoc-fixref -FIXXREF_OPTIONS= +# 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-building.xml \ + overview-programming.xml \ + gi-gir-reference.xml \ + gi-struct-hierarchy.xml \ + version.xml + +# 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 +# +# Set to $(content_files) for simplicity, so we can always +# simply , even for manually +# written .xml files... +expand_content_files=$(content_files) + +# 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. GTKDOC_CFLAGS=-I$(top_srcdir) -I$(top_builddir) $(GTK_DEBUG_FLAGS) +# e.g. GTKDOC_LIBS=$(top_builddir)/gtk/$(gtktargetlib) +GTKDOC_CFLAGS= \ + -I$(top_srcdir) \ + $(GIREPO_CFLAGS) + +GTKDOC_LIBS= \ + $(top_builddir)/libgirepository-1.0.la \ + $(top_builddir)/libgirepository-internals.la \ + $(GIREPO_LIBS) -# include common portion ... +# Other files to distribute +# e.g. EXTRA_DIST += version.xml.in include $(top_srcdir)/gtk-doc.make + # Other files to distribute EXTRA_DIST += version.xml.in -gtk-docs-clean: - rm -fr html tmpl xml - -clean-local: gtk-docs-clean - -######################################################################## - -dist-hook-local: $(BUILT_EXTRA_DIST) - files='$(BUILT_EXTRA_DIST)'; \ - for f in $$files; do \ - if test -f $$f; then d=.; else d=$(srcdir); fi; \ - cp $$d/$$f $(distdir) || exit 1; done +# Files not to distribute +# for --rebuild-types in $(SCAN_OPTIONS), e.g. $(DOC_MODULE).types +# for --rebuild-sections in $(SCAN_OPTIONS) e.g. $(DOC_MODULE)-sections.txt +#DISTCLEANFILES += + +if ENABLE_GTK_DOC +TESTS_ENVIRONMENT = \ + DOC_MODULE=$(DOC_MODULE) DOC_MAIN_SGML_FILE=$(DOC_MAIN_SGML_FILE) \ + SRCDIR=$(abs_srcdir) BUILDDIR=$(abs_builddir) +# Comment this out if you want 'make check' to test you doc status +# and run some sanity checks +## Note: Uncoment this when we start depending on GTK-Doc 1.20 +## which solves https://bugzilla.gnome.org/show_bug.cgi?id=701638 +##TESTS = $(GTKDOC_CHECK) +endif + +gi-docs-clean: clean + cd $(srcdir) && rm -rf xml html -- cgit v1.2.1