GNOME.org
 

[devhelp/docgen: 8/11] Use gi-docgen to generate the devhelp API reference


commit 2153187f83f6f12040abaaf16320c7dcb7fc1dc2
Author: Emmanuele Bassi <ebassi gnome org>
Date:   Thu Jul 15 14:41:05 2021 +0100

    Use gi-docgen to generate the devhelp API reference
    
    The gi-docgen tool uses the introspection data, which means our API
    reference will match the API available to our consumers across multiple
    languages. Additionally, gi-docgen is faster than gtk-doc, and generates
    a better HTML output that can be searched remotely outside of Devhelp.

 .gitignore                     |   4 +-
 devhelp/meson.build            |   2 +-
 docs/reference/api-breaks.md   | 137 +++++++++++++++++++++++++++++++++++++++++
 docs/reference/devhelp.toml.in |  34 ++++++++++
 docs/reference/meson.build     |  81 ++++++++++++------------
 subprojects/gi-docgen.wrap     |   6 ++
 6 files changed, 222 insertions(+), 42 deletions(-)
---
diff --git a/.gitignore b/.gitignore
index 47656a4c..4d0ed8f0 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,2 +1,4 @@
 build/
-_build/
\ No newline at end of file
+_build/
+
+subprojects/gi-docgen
diff --git a/devhelp/meson.build b/devhelp/meson.build
index eef055e7..010e563f 100644
--- a/devhelp/meson.build
+++ b/devhelp/meson.build
@@ -120,7 +120,7 @@ PKG_CONFIG.generate(
   requires_private: LIBDEVHELP_PRIVATE_DEPS
 )
 
-GNOME.generate_gir(
+libdevhelp_gir = GNOME.generate_gir(
   libdevhelp_shared_lib,
   export_packages: 'libdevhelp-@0@'.format(LIBDEVHELP_API_VERSION_FULL),
   header: 'devhelp/devhelp.h',
diff --git a/docs/reference/api-breaks.md b/docs/reference/api-breaks.md
new file mode 100644
index 00000000..a5a3794d
--- /dev/null
+++ b/docs/reference/api-breaks.md
@@ -0,0 +1,137 @@
+Title: API Breaks
+Slug: api-breaks
+
+Devhelp is a quite old piece of software (created in 2001), and as every
+software, the code evolves during its lifetime. So there are sometimes API
+breaks. We try to not break applications depending on the Devhelp API. But
+if we see that a certain API is used nowhere else than the Devhelp
+application itself (or is dead code), we don't hesitate to break the API to
+improve the code.
+
+Currently we try to not break [Anjuta](https://wiki.gnome.org/Apps/Anjuta)
+and [GNOME Builder](https://wiki.gnome.org/Apps/Builder). If your
+application is not listed and depends on the Devhelp API and is Free
+Software, please contact the Devhelp maintainers.
+
+Changes between 3.29.1 and 3.29.2
+---------------------------------
+
+- `DhBookManager` is now completely empty and entirely deprecated, the
+  minimum amount of API is kept to not break Anjuta. It has been replaced by
+  a more flexible infrastructure: [`class@Profile`], [`class@Settings`] and
+  [`class@BookList`]. If your application uses only the default libdevhelp
+  widgets it will still work fine – even if you don't adapt the code of the
+  application – because in that case it will use the default `DhProfile`
+  which contains the same content as how `DhBookManager` was implemented.
+
+- Whether a DhBook is enabled/selected is now decoupled from DhBook:
+  `dh_book_get_enabled()` and `dh_book_set_enabled()` have been removed, as
+  well as the `DhBook::enabled` and `DhBook::disabled` signals. For a book
+  to be enabled it now needs to be part of a [`class@BookList`], which is more
+  flexible because there can be several different `DhBookList`'s in parallel.
+
+- The last parameter of `dh_keyword_model_filter()` has been changed, it is
+  no longer the language (a string, that parameter was deprecated), it is a
+  nullable [`class@Profile`].
+
+- `dh_book_tree_get_selected_book()` has been replaced by
+  [`method@BookTree.get_selected_link`].
+
+Changes between 3.28.0 and 3.29.1
+---------------------------------
+
+- The `DhBookManager:group-by-language` property has been replaced by the
+  [`property@Settings:group-books-by-language`] one.
+
+- [`ctor BookTree new`] now takes a [`class@Profile`] parameter.
+
+Changes between 3.27.1 and 3.27.2
+---------------------------------
+
+- `dh_book_cmp_by_path()` has been removed (dead code).
+
+- The `DhBookManager::language-enabled` and
+  `DhBookManager::language-disabled` signals have been removed (dead code).
+
+- [`class@Sidebar`] is now a subclass of [`class Gtk Grid`], not of
+  [`class Gtk Box`].
+
+- `dh_sidebar_get_selected_book()` has been removed (it was used only inside
+  `DhSidebar`).
+
+- `dh_book_get_completions()` has been replaced by
+  [`method@Book.get_completion`].
+
+Changes between 3.26.0 and 3.27.1
+---------------------------------
+
+- [`ctor Link new`] has been split in two, with [`ctor@Link.new_book`] to
+  create a [`struct@Link`] of `DH_LINK_TYPE_BOOK`.
+
+- The `dh_link_get_file_name()` function has been removed.
+
+- The `dh_book_get_path()` function has been replaced by
+  [`method@Book.get_index_file`].
+
+- The [`ctor Book new`] constructor now takes a `GFile` argument instead of
+  a string path.
+
+- `dh_book_get_name()` has been renamed to [`method@Book.get_id`].
+
+- `dh_book_cmp_by_name()` has been renamed to [`method@Book.cmp_by_id`].
+
+- `dh_link_get_book_name()` has been renamed to
+  [`method@Link.get_book_title`].
+
+- `dh_book_get_keywords()` has been renamed to [`method@Book.get_links`].
+
+- The ownership transfer of the return values of
+  `dh_book_tree_get_selected_book()` and `dh_sidebar_get_selected_book()`
+  have been changed from `(transfer none)` to `(transfer full)`.
+
+Changes between 3.25.1 and 3.25.2
+---------------------------------
+
+- The `page` parameter of [`ctor Link new`] has been removed because it was
+  broken in `dh-parser.c`.  The `book` parameter has also been moved, to
+  group related parameters together.
+
+- The `dh_link_get_page_name()` function has been removed because it was
+  broken and used nowhere.
+
+- The `dh_link_get_type_as_string()` function (which took a
+  [`struct@Link`] parameter) has been removed, and it has been replaced by [`func@LinkType.to_string`]
+  which takes a [`enum@LinkType`] parameter.
+
+Changes between 3.24.0 and 3.25.1
+---------------------------------
+
+- All deprecated APIs have been removed.
+
+- `dh-error.h` is now private.
+
+- The `DhApp`, `DhAssistant` and `DhWindow` classes are now private. `DhApp`
+  is a subclass of `GtkApplication`, and an application can have only one
+  `GtkApplication` instance, so as-is `DhApp` didn't make sense in the
+  library (what if two different libraries have both a subclass of
+  `GtkApplication`?). Since `DhAssistant` and `DhWindow` depend on `DhApp`,
+  they are now also private.
+
+- The `DhLanguage` class is now private, it's currently used
+  only internally by [`class@BookManager`].
+
+- Due to [`class@BookManager`] being now a singleton, there has been the
+  following API changes:
+
+  - `dh_assistant_view_set_book_manager()` has been
+   removed.
+
+  - `dh_keyword_model_set_words()` has been removed.
+
+  - The `DhBookTree:book-manager` property has been removed.
+
+  - API break for [`ctor BookTree new`]/
+
+  - The `DhSidebar:book-manager` property has been removed.
+
+  - The `book_manager` parameter of [`ctor Sidebar new`] is no deprecated.
diff --git a/docs/reference/devhelp.toml.in b/docs/reference/devhelp.toml.in
new file mode 100644
index 00000000..da6f19f1
--- /dev/null
+++ b/docs/reference/devhelp.toml.in
@@ -0,0 +1,34 @@
+[library]
+version = "@version@"
+browse_url = "https://gitlab.gnome.org/GNOME/devhelp/";
+repository_url = "https://gitlab.gnome.org/GNOME/devhelp.git";
+website_url = "https://wiki.gnome.org/Apps/Devhelp";
+authors = "The Devhelp Authors"
+license = "GPL-3.0-or-later"
+description = "A library for discovering, browsing, and searching developer documentation for the GNOME 
project"
+devhelp = true
+search_index = true
+dependencies = ["Gtk-3.0",]
+
+  [dependencies."Gtk-3.0"]
+  name = "GTK 3"
+  description = "The GTK toolkit"
+  docs_url = "https://developer.gnome.org/gtk3/stable/";
+
+  [dependencies."WebKit2-4.0"]
+  name = "WebKitGTK 2"
+  description = "WebKit rendering widget for GTK"
+  docs_url = "https://webkitgtk.org/reference/webkit2gtk/stable/";
+
+[theme]
+name = "basic"
+show_index_summary = true
+show_class_hierarchy = true
+
+[source-location]
+base_url = "https://gitlab.gnome.org/GNOME/devhelp/-/blob/HEAD/devhelp/";
+
+[extra]
+content_files = [
+  "api-breaks.md",
+]
diff --git a/docs/reference/meson.build b/docs/reference/meson.build
index 9d8f92b4..d689e234 100644
--- a/docs/reference/meson.build
+++ b/docs/reference/meson.build
@@ -1,45 +1,46 @@
-subdir('xml')
+docs_dir = get_option('prefix') / get_option('datadir') / 'doc'
 
-configure_file(
-  input: 'devhelp-sections.txt',
-  output: 'devhelp-@0 -sections txt'.format(LIBDEVHELP_API_VERSION),
-  copy: true
+extra_content_files = [
+  'api-breaks.md',
+]
+
+dependency('gi-docgen', version: '>= 2021.6',
+  fallback: ['gi-docgen', 'dummy_dep'],
+  required: get_option('gtk_doc'),
 )
 
-gtkdoc_module_name = 'devhelp-@0@'.format(LIBDEVHELP_API_VERSION)
-html_dir = get_option('prefix') / GNOME.gtkdoc_html_dir(gtkdoc_module_name)
+gidocgen = find_program('gi-docgen', required: get_option('gtk_doc'))
 
-glib_docpath = dependency('glib-2.0').get_pkgconfig_variable('prefix') / 'share/gtk-doc/html/glib'
-gobject_docpath = dependency('gobject-2.0').get_pkgconfig_variable('prefix') / 'share/gtk-doc/html/gobject'
-gio_docpath = dependency('gio-2.0').get_pkgconfig_variable('prefix') / 'share/gtk-doc/html/gio'
-gtk_docpath = dependency('gtk+-3.0').get_pkgconfig_variable('prefix') / 'share/gtk-doc/html/gtk3'
-webkitgtk_docpath = dependency('webkit2gtk-4.0').get_pkgconfig_variable('prefix') / 
'share/gtk-doc/html/webkit2gtk-4.0'
+if get_option('gtk_doc')
+  toml_data = configuration_data()
+  toml_data.set('version', meson.project_version())
 
-GNOME.gtkdoc(
-  gtkdoc_module_name,
-  main_xml: 'devhelp-docs.xml',
-  src_dir: include_directories('../../devhelp/'),
-  dependencies: LIBDEVHELP_SHARED_LIB_DEP,
-  scan_args: ['--rebuild-types'],
-  gobject_typesfile: 'devhelp-@0@.types'.format(LIBDEVHELP_API_VERSION),
-  fixxref_args: [
-    '--html-dir=@0@'.format(html_dir),
-    '--extra-dir=@0@'.format(glib_docpath),
-    '--extra-dir=@0@'.format(gobject_docpath),
-    '--extra-dir=@0@'.format(gio_docpath),
-    '--extra-dir=@0@'.format(gtk_docpath),
-    '--extra-dir=@0@'.format(webkitgtk_docpath)
-  ],
-  content_files: [
-    'api-breaks.xml'
-  ],
-  ignore_headers: [
-    'dh-book-list-simple.h',
-    'dh-dconf-migration.h',
-    'dh-error.h',
-    'dh-parser.h',
-    'dh-search-context.h',
-    'dh-util-lib.h'
-  ],
-  install: true
-)
+  devhelp_toml = configure_file(
+    input: 'devhelp.toml.in',
+    output: 'devhelp-@0@.toml'.format(LIBDEVHELP_API_VERSION),
+    configuration: toml_data,
+    install: true,
+    install_dir: docs_dir / 'devhelp-@0@'.format(LIBDEVHELP_API_VERSION),
+  )
+
+  custom_target('devhelp-doc',
+    input: [devhelp_toml, libdevhelp_gir],
+    output: 'devhelp-@0@'.format(LIBDEVHELP_API_VERSION),
+    command: [
+      gidocgen,
+      'generate',
+      '--quiet',
+      '--fatal-warnings',
+      '--add-include-path=@0@'.format(meson.current_build_dir() / '../../devhelp'),
+      '--config=@INPUT0@',
+      '--output-dir=@OUTPUT@',
+      '--no-namespace-dir',
+      '--content-dir=@0@'.format(meson.current_source_dir()),
+      '@INPUT1@',
+    ],
+    depend_files: extra_content_files,
+    build_by_default: true,
+    install: true,
+    install_dir: docs_dir,
+  )
+endif
diff --git a/subprojects/gi-docgen.wrap b/subprojects/gi-docgen.wrap
new file mode 100644
index 00000000..98cd9211
--- /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
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]