From 0784760df8c6d445fadcfcfb2806a1aac30c31c8 Mon Sep 17 00:00:00 2001 From: Emmanuele Bassi Date: Mon, 22 May 2017 10:26:21 +0100 Subject: build: Modernise the API reference Let's use modern, idiomatic gtk-doc to generate the API reference: - use XInclude - stop using SGML mode with XML files - drop version.xml and use the gtk-doc package entities --- configure.ac | 3 +- docs/Makefile.am | 23 +++---- docs/atk-docs.sgml | 172 ---------------------------------------------------- docs/atk-docs.xml | 146 ++++++++++++++++++++++++++++++++++++++++++++ docs/meson.build | 10 +-- docs/version.xml.in | 1 - 6 files changed, 160 insertions(+), 195 deletions(-) delete mode 100644 docs/atk-docs.sgml create mode 100644 docs/atk-docs.xml delete mode 100644 docs/version.xml.in diff --git a/configure.ac b/configure.ac index 49065be..870844b 100644 --- a/configure.ac +++ b/configure.ac @@ -198,7 +198,7 @@ AC_DEFINE_UNQUOTED(GETTEXT_PACKAGE, ["$GETTEXT_PACKAGE"], GOBJECT_INTROSPECTION_CHECK([1.32.0]) # Documentation support -GTK_DOC_CHECK([1.13]) +GTK_DOC_CHECK([1.25]) # define a MAINT-like variable REBUILD which is set if Perl # and awk are found, so autogenerated sources can be rebuilt @@ -267,7 +267,6 @@ win32/vs12/Makefile win32/vs14/Makefile win32/vs15/Makefile docs/Makefile -docs/version.xml config.h.win32 ]) diff --git a/docs/Makefile.am b/docs/Makefile.am index 88c122b..c87c643 100644 --- a/docs/Makefile.am +++ b/docs/Makefile.am @@ -1,18 +1,16 @@ ## Process this file with automake to produce Makefile.in -AUTOMAKE_OPTIONS = 1.6 - # The name of the module. -DOC_MODULE=atk +DOC_MODULE = atk # The top-level SGML file. -DOC_MAIN_SGML_FILE=atk-docs.sgml +DOC_MAIN_SGML_FILE = atk-docs.xml # Extra options to supply to gtkdoc-scan -SCAN_OPTIONS=--deprecated-guards=G_DISABLE_DEPRECATED +SCAN_OPTIONS = --deprecated-guards=ATK_DISABLE_DEPRECATED # The directory containing the source code (if it contains documentation). -DOC_SOURCE_DIR=$(top_srcdir)/atk $(top_builddir)/atk +DOC_SOURCE_DIR = $(top_srcdir)/atk $(top_builddir)/atk # Used for dependencies HFILE_GLOB = $(top_srcdir)/atk/*.h @@ -28,15 +26,18 @@ IGNORE_HFILES = \ AM_CPPFLAGS = \ -I$(top_srcdir) \ -I$(top_builddir) \ + -DATK_DISABLE_DEPRECATION_WARNINGS \ $(DEP_CFLAGS) -GTKDOC_LIBS = $(top_builddir)/atk/libatk-$(ATK_API_VERSION).la \ - $(DEP_LIBS) +GTKDOC_LIBS = \ + $(top_builddir)/atk/libatk-$(ATK_API_VERSION).la \ + $(DEP_LIBS) # gtkdoc-mkdb related varaibles -MKDB_OPTIONS =--sgml-mode -content_files = \ - version.xml +MKDB_OPTIONS = + +content_files = + HTML_IMAGES = include $(top_srcdir)/gtk-doc.make diff --git a/docs/atk-docs.sgml b/docs/atk-docs.sgml deleted file mode 100644 index 2d9991e..0000000 --- a/docs/atk-docs.sgml +++ /dev/null @@ -1,172 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -]> - - - - ATK - Accessibility Toolkit - for ATK &version; - - - - Overview - - GNOME provides support for accessibility devices using the ATK - framework. This framework defines a set of interfaces to which - graphical interface components adhere. This allows, for instance, - screen readers to read the text of an interface and interact with its - controls. ATK support is built into GTK+ and the rest of the GNOME - platform, so any application using GTK+ will have reasonable - accessibility support for free. - - - - Nonetheless, you should be aware of accessibility issues when when - developing your applications. Although GTK+ interfaces provide - reasonable accessibility by default, you can often improve how well - your program behaves with accessibility tools by providing additional - information to ATK. If you develop custom widgets, you should ensure - that they expose their properties to ATK - - - - - - Base accessibility object - &atk-AtkObject; - - - - Event and toolkit support - &atk-AtkUtil; - - - - ATK Interfaces - &atk-AtkAction; - &atk-AtkComponent; - &atk-AtkDocument; - &atk-AtkEditabletext; - &atk-AtkHyperlinkImpl; - &atk-AtkHypertext; - &atk-AtkImage; - &atk-AtkSelection; - &atk-AtkStreamableContent; - &atk-AtkTable; - &atk-AtkTableCell; - &atk-AtkText; - &atk-AtkValue; - &atk-AtkWindow; - - - - Basic accessible data types - &atk-AtkRange; - &atk-AtkRelation; - &atk-AtkRelationSet; - &atk-AtkState; - &atk-AtkStateSet; - - - - Custom accessible objects - &atk-AtkGObjectAccessible; - &atk-AtkHyperlink; - &atk-AtkNoOpObject; - &atk-AtkPlug; - &atk-AtkSocket; - - - - Utilities - &atk-AtkNoOpObjectFactory; - &atk-AtkObjectFactory; - &atk-AtkRegistry; - &atk-AtkVersion; - - - - Deprecated Interfaces - &atk-AtkMisc; - - - - Index of all symbols - - - Index of deprecated symbols - - - Index of new symbols in 1.3 - - - Index of new symbols in 1.4 - - - Index of new symbols in 1.6 - - - Index of new symbols in 1.9 - - - Index of new symbols in 1.12 - - - Index of new symbols in 1.13 - - - Index of new symbols in 1.20 - - - Index of new symbols in 1.22 - - - Index of new symbols in 1.30 - - - Index of new symbols in 2.2 - - - Index of new symbols in 2.8 - - - Index of new symbols in 2.10 - - - Index of new symbols in 2.12 - - - diff --git a/docs/atk-docs.xml b/docs/atk-docs.xml new file mode 100644 index 0000000..f3dfcce --- /dev/null +++ b/docs/atk-docs.xml @@ -0,0 +1,146 @@ + + + + %gtkdocentities; +]> + + + + ATK - Accessibility Toolkit + for ATK &package_version; + + + + Overview + + GNOME provides support for accessibility devices using the ATK + framework. This framework defines a set of interfaces to which + graphical interface components adhere. This allows, for instance, + screen readers to read the text of an interface and interact with its + controls. ATK support is built into GTK+ and the rest of the GNOME + platform, so any application using GTK+ will have reasonable + accessibility support for free. + + + + Nonetheless, you should be aware of accessibility issues when when + developing your applications. Although GTK+ interfaces provide + reasonable accessibility by default, you can often improve how well + your program behaves with accessibility tools by providing additional + information to ATK. If you develop custom widgets, you should ensure + that they expose their properties to ATK + + + + + + Base accessibility object + + + + + Event and toolkit support + + + + + ATK Interfaces + + + + + + + + + + + + + + + + + + Basic accessible data types + + + + + + + + + Custom accessible objects + + + + + + + + + Utilities + + + + + + + + Deprecated Interfaces + + + + + Index of all symbols + + + Index of deprecated symbols + + + Index of new symbols in 1.3 + + + Index of new symbols in 1.4 + + + Index of new symbols in 1.6 + + + Index of new symbols in 1.9 + + + Index of new symbols in 1.12 + + + Index of new symbols in 1.13 + + + Index of new symbols in 1.20 + + + Index of new symbols in 1.22 + + + Index of new symbols in 1.30 + + + Index of new symbols in 2.2 + + + Index of new symbols in 2.8 + + + Index of new symbols in 2.10 + + + Index of new symbols in 2.12 + + + + + diff --git a/docs/meson.build b/docs/meson.build index d2dac1c..fb26d40 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -1,18 +1,11 @@ subdir('xml') -version_xml_conf = configuration_data() -version_xml_conf.set('ATK_VERSION', meson.project_version()) -configure_file(input: 'version.xml.in', - output: 'version.xml', - configuration: version_xml_conf) - private_headers = [ 'atkmarshal.h', 'atkintl.h', ] content_files = [ - 'version.xml', ] html_images = [ @@ -23,7 +16,7 @@ glib_docpath = join_paths(glib_prefix, 'share', 'gtk-doc', 'html') docpath = join_paths(atk_datadir, 'gtk-doc', 'html') gnome.gtkdoc('atk', - main_xml: 'atk-docs.sgml', + main_xml: 'atk-docs.xml', src_dir: [ join_paths(meson.source_root(), 'atk'), join_paths(meson.build_root(), 'atk'), @@ -37,7 +30,6 @@ gnome.gtkdoc('atk', '--ignore-headers=' + ' '.join(private_headers), ], mkdb_args: [ - '--sgml-mode', '--output-format=xml', ], fixxref_args: [ diff --git a/docs/version.xml.in b/docs/version.xml.in deleted file mode 100644 index e2242c8..0000000 --- a/docs/version.xml.in +++ /dev/null @@ -1 +0,0 @@ -@ATK_VERSION@ -- cgit v1.2.1