# HG changeset patch
# Node ID ee94082f3ae3
# Parent f8226e3d15d7
diff --git a/.hgignore b/.hgignore
--- a/.hgignore
+++ b/.hgignore
@@ -1,3 +1,3 @@
syntax: regexp
build.*\/
-
+^subprojects\/.+\/
diff --git a/convey.yml b/convey.yml
--- a/convey.yml
+++ b/convey.yml
@@ -1,8 +1,7 @@
environment:
- - GNT_VERSION=latest
- - DOCS_REPOSITORY=libgnt/docs
- REGISTRY_HOST=docker.io
- REPOSITORY=libgnt/builders
+ - DOCS_BUILD_IMAGE=${REGISTRY_HOST}/${REPOSITORY}:debian-bullseye-amd64
tasks:
build:
@@ -15,24 +14,24 @@
- debian-bookworm-amd64
- debian-bullseye-amd64
- fedora-34-amd64
+ - libgnt-docs
- build-docs:
+ docs-clean:
+ type: convey/clean
+ files:
+ - libgnt-docs
+ docs-build:
type: docker/run
- image: ${REGISTRY_HOST}/${REPOSITORY}:debian-buster-amd64
+ image: ${DOCS_BUILD_IMAGE}
+ workdir: ${CONVEY_WORKSPACE}
script:
- set -ex
- - cd ${CONVEY_WORKSPACE}
- - meson build-convey
- - ninja -C build-convey libgnt-doc
- build-docs-image:
- type: docker/build
- dockerfile: doc/Dockerfile
- tag: ${REGISTRY_HOST}/${DOCS_REPOSITORY}:${GNT_VERSION}
+ - meson build-docs
+ - ninja -C build-docs doc
+ docs-export:
+ type: docker/export
files:
- - build-convey/doc/html:.
- publish-docs-image:
- type: docker/push
- image: ${REGISTRY_HOST}/${DOCS_REPOSITORY}:${GNT_VERSION}
+ - build-docs/doc/libgnt:libgnt-docs
export:
type: docker/export
@@ -46,24 +45,10 @@
docs:
stages:
- tasks:
- - import
- - build-docs
- - build-docs-image
- ci-docs:
- stages:
- - name: prep
- tasks:
- - login
- - name: build
- tasks:
- - import
- - build-docs
- - build-docs-image
- - publish-docs-image
- - name: final
- run: always
- tasks:
- - logout
+ - docs-clean
+ - import
+ - docs-build
+ - docs-export
clean:
stages:
diff --git a/doc/Dockerfile b/doc/Dockerfile
deleted file mode 100644
--- a/doc/Dockerfile
+++ /dev/null
@@ -1,6 +0,0 @@
-FROM rwgrim/goserve
-
-EXPOSE 3000
-
-COPY html html
-
diff --git a/doc/libgnt-docs.xml b/doc/libgnt-docs.xml
deleted file mode 100644
--- a/doc/libgnt-docs.xml
+++ /dev/null
@@ -1,158 +0,0 @@
-
-
-
-%version;
-]>
-
-
- GNT Reference Manual
-
- GNT &version;
-
- GNT (GLib Ncurses Toolkit) is an ncurses toolkit for creating text-mode
- graphical user interfaces in a fast and easy way.
-
-
-
-
-
- Object Hierarchy
-
-
-
-
-
- Core API Reference
-
-
-
-
-
-
-
-
-
-
- Widget Class Reference
-
-
- General Widget Classes
-
-
-
-
-
-
-
- Windows and Window Management
-
-
-
-
-
-
-
- Display Widgets
-
-
-
-
-
-
-
-
-
- Button Widgets
-
-
-
-
-
-
- Menu and Combo Box Widgets
-
-
-
-
-
-
-
-
- Text Widgets
-
-
-
-
-
-
-
-
-
- Migrating from Previous Versions of GNT
-
-
-
- This part describes what you need to change in programs using older
- versions of GNT so that they can use the new features.
-
-
-
-
-
-
-
- Appendices
-
- API Index
-
-
-
- Index of deprecated symbols
-
-
-
- Index of new symbols in 3.0.0
-
-
-
- Index of new symbols in 2.14.0
-
-
-
- Index of new symbols in 2.7.3
-
-
-
- Index of new symbols in 2.6.0
-
-
-
- Index of new symbols in 2.4.2
-
-
-
- Index of new symbols in 2.4.0
-
-
-
- Index of new symbols in 2.3.0
-
-
-
- Index of new symbols in 2.2.0
-
-
-
- Index of new symbols in 2.1.1
-
-
-
- Index of new symbols in 2.1.0
-
-
-
-
-
diff --git a/doc/libgnt.toml.in b/doc/libgnt.toml.in
new file mode 100644
--- /dev/null
+++ b/doc/libgnt.toml.in
@@ -0,0 +1,40 @@
+[library]
+version = @GNT_VERSION@
+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"
+logo_url = ""
+license = "LGPL-2.1-or-later"
+description = "GLib Ncurses Toolkit"
+dependencies = [ "GLib-2.0", "GObject-2.0" ]
+devhelp = true
+search_index = true
+
+ [dependencies."GLib-2.0"]
+ name = "GLib"
+ description = "General-purpose, portable utility library."
+ docs_url = "https://docs.gtk.org/glib/"
+
+ [dependencies."GObject-2.0"]
+ name = "GObject"
+ description = "The base type system library"
+ docs_url = "https://docs.gtk.org/gobject/"
+
+[theme]
+name = "basic"
+show_index_summary = true
+show_class_hierarchy = true
+
+[source-location]
+base_url = "https://keep.imfreedom.org/libgnt/libgnt/file/default/"
+
+[extra]
+# The same order will be used when generating the index
+content_files = [
+ "migrating-2to3.md",
+]
+content_images = [
+]
+urlmap_file = "urlmap.js"
+
diff --git a/doc/meson.build b/doc/meson.build
--- a/doc/meson.build
+++ b/doc/meson.build
@@ -1,50 +1,49 @@
-DOC_MODULE = 'libgnt'
-
-# Extra content files, other than the main one.
-content_files = [
- 'migrating-2to3.xml',
+libgnt_doc_content_files = [
+ 'migrating-2to3.md',
]
-# Header files or dirs to ignore when scanning. Use base file/dir names
-ignore_headers = [
- 'test',
- 'wms',
- 'gnt.h',
- 'gntinternal.h',
- 'gnt-skel.h',
- 'gntboxprivate.h',
- 'gntconfig.h',
- 'gntmainprivate.h',
- 'gntmarshal.h',
- 'gntmenuprivate.h',
- 'gntmenuitemprivate.h',
- 'gntncurses.h',
- 'gntstyleprivate.h',
- 'gnttreeprivate.h',
- 'gnttextviewprivate.h',
- 'gntwidgetprivate.h',
- 'gntwmprivate.h',
- 'gntwsprivate.h',
-]
+if get_option('doc')
+ if not get_option('introspection')
+ error('Documentation requires GObject Introspection.')
+ endif
+
+ 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 : true,
+ install_dir : docs_dir / 'libgnt',
+ )
-# Extra options to supply to gtkdoc-scan.
-scan_args = [
- '--deprecated-guards=GNT_DISABLE_DEPRECATED',
- '--rebuild-types',
- '--rebuild-sections',
-]
+ libgnt_doc = custom_target('libgnt-doc',
+ input : [ libgnt_toml, libgnt_gir[0] ],
+ output : 'libgnt',
+ command : [
+ gidocgen,
+ 'generate',
+ '--quiet',
+ '--fatal-warnings',
+ '--config=@INPUT0@',
+ '--output-dir=@OUTPUT@',
+ '--no-namespace-dir',
+ '--content-dir=@0@'.format(meson.current_source_dir()),
+ '@INPUT1@'
+ ],
+ depend_files : [ libgnt_doc_content_files ],
+ build_by_default : true,
+ install : true,
+ install_dir : docs_dir,
+ )
-configure_file(
- input : 'version.xml.in',
- output : 'version.xml',
- configuration : gnt_config)
+ alias_target('doc', [libgnt_doc])
+endif
-gnome.gtkdoc(DOC_MODULE,
- main_xml : DOC_MODULE + '-docs.xml',
- content_files : content_files,
- src_dir : libgnt_inc,
- dependencies : libgnt_dep,
- install : true,
- ignore_headers : ignore_headers,
- scan_args : scan_args,
- gobject_typesfile : DOC_MODULE + '.types')
diff --git a/doc/migrating-2to3.xml b/doc/migrating-2to3.md
rename from doc/migrating-2to3.xml
rename to doc/migrating-2to3.md
--- a/doc/migrating-2to3.xml
+++ b/doc/migrating-2to3.md
@@ -1,122 +1,71 @@
-
-
-]>
-
- Migrating from GNT 2.x to 3
+Title: Migrating from GNT 2.x to 3.0
+Slug: 3.0 Migration
+
+## 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 to build against GNT 3.
-
+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.
-
- 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 2.14 series.
-
+### Preparation in GNT 2.x
-
- 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 replacements. The API reference for GNT 2 also
- includes an index of all
- deprecated symbols.
-
-
- 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
- following:
-
-
- GNT_DISABLE_DEPRECATED to hide deprecated symbols.
-
-
- GNTSEAL_ENABLE 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
- warnings.
-
-
-
+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.
+
+#### 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
+replacements.
+
+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
+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 warnings.
-
- Changes that need to be done at the time of the switch
+### 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 impractical.
-
+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.
+
+#### Removed internal API
-
- Removed internal API
+The following tag names have been removed from the API entirely; use the name
+without the underscore instead:
-
- The following tag names have been removed from the API entirely; use
- the name without the underscore instead:
-
- enum _GntFileType
- enum _GntMouseEvent
- enum _GntParamFlags
- enum _GntProgressBarOrientation
- enum _GntTreeColumnFlag
-
+ * `enum _GntFileType`
+ * `enum _GntMouseEvent`
+ * `enum _GntParamFlags`
+ * `enum _GntProgressBarOrientation`
+ * `enum _GntTreeColumnFlag`
- The following items were removed entirely:
-
-
- enum _GntKeyPressMode and GntKeyPressMode
-
-
- enum _GntWidgetFlags and GntWidgetFlags
-
-
-
-
+The following items were removed entirely:
+
+ * `enum _GntKeyPressMode`
+ * `GntKeyPressMode`
+ * `enum _GntWidgetFlags`
+ * `GntWidgetFlags`
+
+#### Changed API
-
- Changed API
-
- The following items have been changed as part of the API break:
-
-
- ENTRY_CHAR renamed to %GNT_ENTRY_CHAR
-
-
- g_hash_table_duplicate renamed to
- gnt_hash_table_duplicate()
-
-
- GDupFunc renamed to #GntDuplicateFunc
-
-
- GntTreeHashFunc removed in favor of #GHashFunc
-
-
- GntTreeHashEqualityFunc removed in favor of #GEqualFunc
-
-
-
-
-
-
+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]
+
diff --git a/doc/urlmap.js b/doc/urlmap.js
new file mode 100644
--- /dev/null
+++ b/doc/urlmap.js
@@ -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
+baseURLs = [
+ [ 'GLib', 'https://docs.gtk.org/glib/' ],
+ [ 'GObject', 'https://docs.gtk.org/gobject/' ],
+]
diff --git a/doc/version.xml.in b/doc/version.xml.in
deleted file mode 100644
--- a/doc/version.xml.in
+++ /dev/null
@@ -1,1 +0,0 @@
-
diff --git a/meson.build b/meson.build
--- a/meson.build
+++ b/meson.build
@@ -293,7 +293,9 @@
identifier_prefix : 'Gnt',
nsversion : '@0@.@1@'.format(gnt_major_version, gnt_minor_version),
install : true,
- extra_args : ['-DGNT_COMPILATION', '--quiet'])
+ extra_args : ['-DGNT_COMPILATION', '--quiet'],
+ export_packages : ['gnt3'],
+ header : 'gnt.h')
libgnt_generated_targets += libgnt_gir
endif
@@ -309,6 +311,5 @@
subdir('wms')
subdir('test')
-if get_option('doc')
- subdir('doc')
-endif
+subdir('doc')
+
diff --git a/subprojects/gi-docgen.wrap b/subprojects/gi-docgen.wrap
new file mode 100644
--- /dev/null
+++ b/subprojects/gi-docgen.wrap
@@ -0,0 +1,6 @@
+[wrap-git]
+directory=gi-docgen
+url=https://gitlab.gnome.org/GNOME/gi-docgen.git
+push-url=ssh://git@gitlab.gnome.org:GNOME/gi-docgen.git
+revision=main
+depth=1