Migrate to gi-docgen
Testing Done:
built the docs and verified they were working as expected.
Reviewed at https://reviews.imfreedom.org/r/952/
--- a/.hgignore Tue Sep 28 01:08:07 2021 -0500
+++ b/.hgignore Thu Sep 30 01:22:40 2021 -0500
@@ -1,3 +1,3 @@
--- a/convey.yml Tue Sep 28 01:08:07 2021 -0500
+++ b/convey.yml Thu Sep 30 01:22:40 2021 -0500
@@ -1,8 +1,7 @@
- - DOCS_REPOSITORY=libgnt/docs - REGISTRY_HOST=docker.io
- REPOSITORY=libgnt/builders
+ - DOCS_BUILD_IMAGE=${REGISTRY_HOST}/${REPOSITORY}:debian-bullseye-amd64 @@ -15,24 +14,24 @@
- image: ${REGISTRY_HOST}/${REPOSITORY}:debian-buster-amd64+ image: ${DOCS_BUILD_IMAGE} + workdir: ${CONVEY_WORKSPACE} - - cd ${CONVEY_WORKSPACE}- - ninja -C build-convey libgnt-doc- dockerfile: doc/Dockerfile- tag: ${REGISTRY_HOST}/${DOCS_REPOSITORY}:${GNT_VERSION}+ - ninja -C build-docs doc - - build-convey/doc/html:.- image: ${REGISTRY_HOST}/${DOCS_REPOSITORY}:${GNT_VERSION}+ - build-docs/doc/libgnt:libgnt-docs @@ -46,24 +45,10 @@
--- a/doc/Dockerfile Tue Sep 28 01:08:07 2021 -0500
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,6 +0,0 @@
--- a/doc/libgnt-docs.xml Tue Sep 28 01:08:07 2021 -0500
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,158 +0,0 @@
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"- "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [-<!ENTITY % local.common.attrib "xmlns:xi CDATA #FIXED 'http://www.w3.org/2003/XInclude'">-<!ENTITY % version SYSTEM "version.xml">-<book id="index" xmlns:xi="http://www.w3.org/2003/XInclude">- <title>GNT Reference Manual</title>- <title>GNT &version;</title>- GNT (GLib Ncurses Toolkit) is an ncurses toolkit for creating text-mode- graphical user interfaces in a fast and easy way.- <part id="object-hierarchy">- <title>Object Hierarchy</title>- <xi:include href="xml/tree_index.sgml"/>- <title>Core API Reference</title>- <xi:include href="xml/gntversion.xml" />- <xi:include href="xml/gntcolors.xml" />- <xi:include href="xml/gntkeys.xml" />- <xi:include href="xml/gntmain.xml" />- <xi:include href="xml/gntstyle.xml" />- <xi:include href="xml/gntutils.xml" />- <title>Widget Class Reference</title>- <title>General Widget Classes</title>- <xi:include href="xml/gntbindable.xml" />- <xi:include href="xml/gntbox.xml" />- <xi:include href="xml/gntwidget.xml" />- <title>Windows and Window Management</title>- <xi:include href="xml/gntfilesel.xml" />- <xi:include href="xml/gntwindow.xml" />- <xi:include href="xml/gntwm.xml" />- <xi:include href="xml/gntws.xml" />- <title>Display Widgets</title>- <xi:include href="xml/gntlabel.xml" />- <xi:include href="xml/gntline.xml" />- <xi:include href="xml/gntprogressbar.xml" />- <xi:include href="xml/gntslider.xml" />- <xi:include href="xml/gnttree.xml" />- <title>Button Widgets</title>- <xi:include href="xml/gntbutton.xml" />- <xi:include href="xml/gntcheckbox.xml" />- <title>Menu and Combo Box Widgets</title>- <xi:include href="xml/gntmenu.xml" />- <xi:include href="xml/gntmenuitem.xml" />- <xi:include href="xml/gntmenuitemcheck.xml" />- <xi:include href="xml/gntcombobox.xml" />- <title>Text Widgets</title>- <xi:include href="xml/gntclipboard.xml" />- <xi:include href="xml/gntentry.xml" />- <xi:include href="xml/gnttextview.xml" />- <!-- Migration guides -->- <title>Migrating from Previous Versions of GNT</title>- This part describes what you need to change in programs using older- versions of GNT so that they can use the new features.- <xi:include href="migrating-2to3.xml" />- <title>Appendices</title>- <index id="api-index-full">- <title>API Index</title>- <xi:include href="xml/api-index-full.xml"><xi:fallback /></xi:include>- <index id="api-deprecated">- <title>Index of deprecated symbols</title>- <xi:include href="xml/api-index-deprecated.xml"><xi:fallback /></xi:include>- <title>Index of new symbols in 3.0.0</title>- <xi:include href="xml/api-index-3.0.0.xml"><xi:fallback /></xi:include>- <index id="api-2.14.0">- <title>Index of new symbols in 2.14.0</title>- <xi:include href="xml/api-index-2.14.0.xml"><xi:fallback /></xi:include>- <title>Index of new symbols in 2.7.3</title>- <xi:include href="xml/api-index-2.7.3.xml"><xi:fallback /></xi:include>- <title>Index of new symbols in 2.6.0</title>- <xi:include href="xml/api-index-2.6.0.xml"><xi:fallback /></xi:include>- <title>Index of new symbols in 2.4.2</title>- <xi:include href="xml/api-index-2.4.2.xml"><xi:fallback /></xi:include>- <title>Index of new symbols in 2.4.0</title>- <xi:include href="xml/api-index-2.4.0.xml"><xi:fallback /></xi:include>- <title>Index of new symbols in 2.3.0</title>- <xi:include href="xml/api-index-2.3.0.xml"><xi:fallback /></xi:include>- <title>Index of new symbols in 2.2.0</title>- <xi:include href="xml/api-index-2.2.0.xml"><xi:fallback /></xi:include>- <title>Index of new symbols in 2.1.1</title>- <xi:include href="xml/api-index-2.1.1.xml"><xi:fallback /></xi:include>- <title>Index of new symbols in 2.1.0</title>- <xi:include href="xml/api-index-2.1.0.xml"><xi:fallback /></xi:include>- <xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/libgnt.toml.in Thu Sep 30 01:22:40 2021 -0500
@@ -0,0 +1,40 @@
+browse_url = "https://keep.imfreedom.org/libgnt/libgnt/" +repository_url = "https://keep.imfreedom.org/libgnt/libgnt/" +website_url = "https://keep.imfreedom.org/libgnt/libgnt/" +authors = "LibGnt Developers" +license = "LGPL-2.1-or-later" +description = "GLib Ncurses Toolkit" +dependencies = [ "GLib-2.0", "GObject-2.0" ] + [dependencies."GLib-2.0"] + description = "General-purpose, portable utility library." + docs_url = "https://docs.gtk.org/glib/" + [dependencies."GObject-2.0"] + description = "The base type system library" + docs_url = "https://docs.gtk.org/gobject/" +show_index_summary = true +show_class_hierarchy = true +base_url = "https://keep.imfreedom.org/libgnt/libgnt/file/default/" +# The same order will be used when generating the index +urlmap_file = "urlmap.js" --- a/doc/meson.build Tue Sep 28 01:08:07 2021 -0500
+++ b/doc/meson.build Thu Sep 30 01:22:40 2021 -0500
@@ -1,50 +1,49 @@
-# Extra content files, other than the main one.+libgnt_doc_content_files = [ -# Header files or dirs to ignore when scanning. Use base file/dir names- 'gntmenuitemprivate.h',- 'gnttextviewprivate.h',+ if not get_option('introspection') + error('Documentation requires GObject Introspection.') + gidocgen_dep = dependency( + 'gi-docgen', version: '>= 2021.1', + fallback: ['gi-docgen', 'dummy_dep'], + required: get_option('doc') + gidocgen = find_program('gi-docgen', required : get_option('doc')) + docs_dir = get_option('prefix') / get_option('datadir') / 'doc' + libgnt_toml = configure_file( + input : 'libgnt.toml.in', + output : 'libgnt.toml', + configuration : gnt_config, + install_dir : docs_dir / 'libgnt', -# Extra options to supply to gtkdoc-scan.- '--deprecated-guards=GNT_DISABLE_DEPRECATED',+ libgnt_doc = custom_target('libgnt-doc', + input : [ libgnt_toml, libgnt_gir[0] ], + '--output-dir=@OUTPUT@', + '--content-dir=@0@'.format(meson.current_source_dir()), + depend_files : [ libgnt_doc_content_files ], + build_by_default : true, + install_dir : docs_dir,
- input : 'version.xml.in',- output : 'version.xml',- configuration : gnt_config)+ alias_target('doc', [libgnt_doc]) -gnome.gtkdoc(DOC_MODULE,- main_xml : DOC_MODULE + '-docs.xml',- content_files : content_files,- dependencies : libgnt_dep,- ignore_headers : ignore_headers,- gobject_typesfile : DOC_MODULE + '.types')--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/migrating-2to3.md Thu Sep 30 01:22:40 2021 -0500
@@ -0,0 +1,71 @@
+Title: Migrating from GNT 2.x to 3.0 +## Migrating from GNT 2.x to 3.0 +GNT 3 is a major new version of GNT that breaks both API and ABI compared to +GNT 2.x. There are a number of steps that you can take to prepare your GNT 2.x +application for the switch to GNT 3. After that, there's a small number of +adjustments that you may have to do when you actually switch your application +### Preparation in GNT 2.x +The steps outlined in the following sections assume that your application is +working with GNT 2.14, which is the final stable release of GNT 2.x. It +includes all the necessary APIs and tools to help you port your application +to GNT 3. If you are still using an older version of GNT 2.x, you should first +get your application to build and work with the latest minor release in the +#### Do not use deprecated symbols +Over the years, a number of functions have been deprecated. These deprecations +are clearly spelled out in the API reference, with hints about the recommended +To verify that your program does not use any deprecated symbols, you can use +preprocessor defines to remove deprecated symbols from the header files. As +part of your compilation process, you may define `GNT_DISABLE_DEPRECATED` to +hide deprecated symbols as well as `GNTSEAL_ENABLE` to hide internal struct +Note that some parts of our API, such as enumeration values, are not well +covered by the deprecation warnings. In most cases, using them will require you +to also use deprecated functions, which will trigger warnings. +### Changes that need to be done at the time of the switch +This section outlines porting tasks that you need to tackle when you get to the +point that you actually build your application against GNT 3. Making it +possible to prepare for these in GNT 2 would have been either impossible or +#### Removed internal API +The following tag names have been removed from the API entirely; use the name +without the underscore instead: + * `enum _GntMouseEvent` + * `enum _GntParamFlags` + * `enum _GntProgressBarOrientation` + * `enum _GntTreeColumnFlag` +The following items were removed entirely: + * `enum _GntKeyPressMode` + * `enum _GntWidgetFlags` +The following items have been changed as part of the API break: + * `ENTRY_CHAR` renamed to [const@Gnt.ENTRY_CHAR] + * `g_hash_table_duplicate` renamed to [func@Gnt.hash_table_duplicate] + * `GDupFunc` renamed to [callback@Gnt.DuplicateFunc] + * `GntTreeHashFunc` removed in favor of [callback@GLib.HashFunc] + * `GntTreeHashEqualityFunc` removed in favor of [callback@GLib.EqualFunc] --- a/doc/migrating-2to3.xml Tue Sep 28 01:08:07 2021 -0500
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,122 +0,0 @@
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"- "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [-<!ENTITY % local.common.attrib "xmlns:xi CDATA #FIXED 'http://www.w3.org/2003/XInclude'">-<chapter id="migrating-2-to-3">- <title>Migrating from GNT 2.x to 3</title>- GNT 3 is a major new version of GNT that breaks both API and ABI compared- to GNT 2.x. There are a number of steps that you can take to prepare your- GNT 2.x application for the switch to GNT 3. After that, there's a small- number of adjustments that you may have to do when you actually switch your- application to build against GNT 3.- <title>Preparation in GNT 2.x</title>- The steps outlined in the following sections assume that your application- is working with GNT 2.14, which is the final stable release of GNT 2.x.- It includes all the necessary APIs and tools to help you port your- application to GNT 3. If you are still using an older version of GNT 2.x,- you should first get your application to build and work with the latest- minor release in the 2.14 series.- <title>Do not use deprecated symbols</title>- Over the years, a number of functions have been deprecated. These- deprecations are clearly spelled out in the API reference, with hints- about the recommended replacements. The API reference for GNT 2 also- includes an <link linkend="api-index-deprecated">index of all- deprecated symbols</link>.- To verify that your program does not use any deprecated symbols, you- can use preprocessor defines to remove deprecated symbols from the- header files. As part of your compilation process, you may define the- <code>GNT_DISABLE_DEPRECATED</code> to hide deprecated symbols.- <code>GNTSEAL_ENABLE</code> to hide internal struct members.- Note that some parts of our API, such as enumeration values, are not- well covered by the deprecation warnings. In most cases, using them- will require you to also use deprecated functions, which will trigger- <title>Changes that need to be done at the time of the switch</title>- This section outlines porting tasks that you need to tackle when you get- to the point that you actually build your application against GNT 3.- Making it possible to prepare for these in GNT 2 would have been either- impossible or impractical.- <title>Removed internal API</title>- The following tag names have been removed from the API entirely; use- the name without the underscore instead:- <listitem><code>enum _GntFileType</code></listitem>- <listitem><code>enum _GntMouseEvent</code></listitem>- <listitem><code>enum _GntParamFlags</code></listitem>- <listitem><code>enum _GntProgressBarOrientation</code></listitem>- <listitem><code>enum _GntTreeColumnFlag</code></listitem>- The following items were removed entirely:- <code>enum _GntKeyPressMode</code> and <code>GntKeyPressMode</code>- <code>enum _GntWidgetFlags</code> and <code>GntWidgetFlags</code>- <title>Changed API</title>- The following items have been changed as part of the API break:- <code>ENTRY_CHAR</code> renamed to %GNT_ENTRY_CHAR- <code>g_hash_table_duplicate</code> renamed to- gnt_hash_table_duplicate()- <code>GDupFunc</code> renamed to #GntDuplicateFunc- <code>GntTreeHashFunc</code> removed in favor of #GHashFunc- <code>GntTreeHashEqualityFunc</code> removed in favor of #GEqualFunc--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/urlmap.js Thu Sep 30 01:22:40 2021 -0500
@@ -0,0 +1,8 @@
+// SPDX-FileCopyrightText: 2021 GNOME Foundation +// SPDX-License-Identifier: LGPL-2.1-or-later +// A map between namespaces and base URLs for their online documentation + [ 'GLib', 'https://docs.gtk.org/glib/' ], + [ 'GObject', 'https://docs.gtk.org/gobject/' ], --- a/doc/version.xml.in Tue Sep 28 01:08:07 2021 -0500
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,1 +0,0 @@
-<!ENTITY version @GNT_VERSION@>--- a/meson.build Tue Sep 28 01:08:07 2021 -0500
+++ b/meson.build Thu Sep 30 01:22:40 2021 -0500
@@ -293,7 +293,9 @@
identifier_prefix : 'Gnt',
nsversion : '@0@.@1@'.format(gnt_major_version, gnt_minor_version),
- extra_args : ['-DGNT_COMPILATION', '--quiet'])+ extra_args : ['-DGNT_COMPILATION', '--quiet'], + export_packages : ['gnt3'], libgnt_generated_targets += libgnt_gir
@@ -309,6 +311,5 @@
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/subprojects/gi-docgen.wrap Thu Sep 30 01:22:40 2021 -0500
@@ -0,0 +1,6 @@
+url=https://gitlab.gnome.org/GNOME/gi-docgen.git +push-url=ssh://git@gitlab.gnome.org:GNOME/gi-docgen.git
