From 548ec9f186d373c4e55528a04d78450f6f2fceef Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Wed, 13 Mar 2024 16:46:06 +0000 Subject: [PATCH] docs: Reduce nesting of documentation directories MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The `gi-docgen` tool is not designed to be used like that. In particular, when nesting documentation directories, the generated `*.devhelp2` files (needed by Devhelp to show the documentation) are nested one directory level too deep for Devhelp to find them, and hence are useless, and the documentation doesn’t show up in this common documentation viewer. So, change the installed documentation directory hierarchy: * `${PREFIX}/share/doc/glib-2.0/gio` → `${PREFIX}/share/doc/gio-2.0` * `${PREFIX}/share/doc/glib-2.0/glib-unix` → `${PREFIX}/share/doc/glib-unix-2.0` * `${PREFIX}/share/doc/glib-2.0/gobject` → `${PREFIX}/share/doc/gobject-2.0` * etc. * `${PREFIX}/share/doc/glib-2.0/glib` → `${PREFIX}/share/doc/glib-2.0` This is going to seem like pointless churn (the contents of the documentation have not changed), and packagers may mourn the split of content in `/usr/share/doc` from `/usr/share/doc/${package_name}` to `/usr/share/doc/${pkg_config_id}` instead, but that seems to be the best approach to fix this issue in GLib. gi-docgen’s behaviour does feel fairly consistent and correct with the rest of how it works (single output directory). Signed-off-by: Philip Withnall Fixes: #3287 --- .gitlab-ci.yml | 24 ++++++++++++------------ .gitlab-ci/test-msys2.sh | 4 ++-- docs/reference/gio/meson.build | 6 +++--- docs/reference/girepository/meson.build | 2 +- docs/reference/glib/meson.build | 6 +++--- docs/reference/gmodule/meson.build | 2 +- docs/reference/gobject/meson.build | 2 +- docs/reference/meson.build | 2 +- 8 files changed, 24 insertions(+), 24 deletions(-) diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index be19b6bfd..f8dc428c3 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -200,13 +200,13 @@ fedora-x86_64: # Copy the built documentation to an artifact directory. The build for docs.gtk.org # can then pull it from there — see https://gitlab.gnome.org/GNOME/gtk/-/blob/docs-gtk-org/README.md - mkdir -p _reference/ - - mv _build/docs/reference/glib/glib/ _reference/glib/ - - mv _build/docs/reference/glib/glib-unix/ _reference/glib-unix/ - - mv _build/docs/reference/gmodule/gmodule/ _reference/gmodule/ - - mv _build/docs/reference/gobject/gobject/ _reference/gobject/ - - mv _build/docs/reference/gio/gio/ _reference/gio/ - - mv _build/docs/reference/gio/gio-unix/ _reference/gio-unix/ - - mv _build/docs/reference/girepository/girepository/ _reference/girepository/ + - mv _build/docs/reference/glib/glib-2.0/ _reference/glib/ + - mv _build/docs/reference/glib/glib-unix-2.0/ _reference/glib-unix/ + - mv _build/docs/reference/gmodule/gmodule-2.0/ _reference/gmodule/ + - mv _build/docs/reference/gobject/gobject-2.0/ _reference/gobject/ + - mv _build/docs/reference/gio/gio-2.0/ _reference/gio/ + - mv _build/docs/reference/gio/gio-unix-2.0/ _reference/gio-unix/ + - mv _build/docs/reference/girepository/girepository-2.0/ _reference/girepository/ artifacts: reports: junit: @@ -805,11 +805,11 @@ dist-job: - meson dist -C _build # Compile again to build the docs - meson compile -C _build - - tar -c -J -f "glib-docs-$CI_COMMIT_TAG.tar.xz" -C _build/docs/reference/glib glib - - tar -c -J -f "gmodule-docs-$CI_COMMIT_TAG.tar.xz" -C _build/docs/reference/gmodule gmodule - - tar -c -J -f "gobject-docs-$CI_COMMIT_TAG.tar.xz" -C _build/docs/reference/gobject gobject - - tar -c -J -f "gio-docs-$CI_COMMIT_TAG.tar.xz" -C _build/docs/reference/gio gio - - tar -c -J -f "girepository-docs-$CI_COMMIT_TAG.tar.xz" -C _build/docs/reference/girepository girepository + - tar -c -J -f "glib-docs-$CI_COMMIT_TAG.tar.xz" -C _build/docs/reference/glib glib-2.0 + - tar -c -J -f "gmodule-docs-$CI_COMMIT_TAG.tar.xz" -C _build/docs/reference/gmodule gmodule-2.0 + - tar -c -J -f "gobject-docs-$CI_COMMIT_TAG.tar.xz" -C _build/docs/reference/gobject gobject-2.0 + - tar -c -J -f "gio-docs-$CI_COMMIT_TAG.tar.xz" -C _build/docs/reference/gio gio-2.0 + - tar -c -J -f "girepository-docs-$CI_COMMIT_TAG.tar.xz" -C _build/docs/reference/girepository girepository-2.0 artifacts: paths: - "${CI_PROJECT_DIR}/_build/glib-docs-$CI_COMMIT_TAG.tar.xz" diff --git a/.gitlab-ci/test-msys2.sh b/.gitlab-ci/test-msys2.sh index 304f94cf9..e03cccf15 100755 --- a/.gitlab-ci/test-msys2.sh +++ b/.gitlab-ci/test-msys2.sh @@ -76,5 +76,5 @@ fi # Copy the built documentation to an artifact directory. The build for docs.gtk.org # can then pull it from there — see https://gitlab.gnome.org/GNOME/gtk/-/blob/docs-gtk-org/README.md mkdir -p _reference/ -mv _build/docs/reference/glib/glib-win32/ _reference/glib-win32/ -mv _build/docs/reference/gio/gio-win32/ _reference/gio-win32/ \ No newline at end of file +mv _build/docs/reference/glib/glib-win32-2.0/ _reference/glib-win32/ +mv _build/docs/reference/gio/gio-win32-2.0/ _reference/gio-win32/ \ No newline at end of file diff --git a/docs/reference/gio/meson.build b/docs/reference/gio/meson.build index 3bb321e9a..35ea67b37 100644 --- a/docs/reference/gio/meson.build +++ b/docs/reference/gio/meson.build @@ -48,7 +48,7 @@ if get_option('documentation') and enable_gir custom_target('gio-docs', input: [ gio_toml, gio_gir[0] ], - output: 'gio', + output: 'gio-2.0', command: [ gidocgen, 'generate', @@ -70,7 +70,7 @@ if get_option('documentation') and enable_gir custom_target('gio-win32-docs', input: [ gio_win32_toml, gio_win32_gir[0] ], - output: 'gio-win32', + output: 'gio-win32-2.0', command: [ gidocgen, 'generate', @@ -91,7 +91,7 @@ if get_option('documentation') and enable_gir custom_target('gio-unix-docs', input: [ gio_unix_toml, gio_unix_gir[0] ], - output: 'gio-unix', + output: 'gio-unix-2.0', command: [ gidocgen, 'generate', diff --git a/docs/reference/girepository/meson.build b/docs/reference/girepository/meson.build index 2d14ffd8a..815e3db98 100644 --- a/docs/reference/girepository/meson.build +++ b/docs/reference/girepository/meson.build @@ -34,7 +34,7 @@ if get_option('documentation') and enable_gir custom_target('girepository-docs', input: [ girepository_toml, girepository_gir[0] ], - output: 'girepository', + output: 'girepository-2.0', command: [ gidocgen, 'generate', diff --git a/docs/reference/glib/meson.build b/docs/reference/glib/meson.build index 1777e537e..e5e6726e2 100644 --- a/docs/reference/glib/meson.build +++ b/docs/reference/glib/meson.build @@ -106,7 +106,7 @@ if get_option('documentation') and enable_gir custom_target('glib-docs', input: [ glib_toml, glib_gir[0] ], - output: 'glib', + output: 'glib-2.0', command: [ gidocgen, 'generate', @@ -128,7 +128,7 @@ if get_option('documentation') and enable_gir custom_target('glib-win32-docs', input: [ glib_win32_toml, glib_win32_gir[0] ], - output: 'glib-win32', + output: 'glib-win32-2.0', command: [ gidocgen, 'generate', @@ -149,7 +149,7 @@ if get_option('documentation') and enable_gir custom_target('glib-unix-docs', input: [ glib_unix_toml, glib_unix_gir[0] ], - output: 'glib-unix', + output: 'glib-unix-2.0', command: [ gidocgen, 'generate', diff --git a/docs/reference/gmodule/meson.build b/docs/reference/gmodule/meson.build index 25a2e4e99..8c9837d29 100644 --- a/docs/reference/gmodule/meson.build +++ b/docs/reference/gmodule/meson.build @@ -7,7 +7,7 @@ if get_option('documentation') and enable_gir custom_target('gmodule-docs', input: [ gmodule_toml, gmodule_gir[0] ], - output: 'gmodule', + output: 'gmodule-2.0', command: [ gidocgen, 'generate', diff --git a/docs/reference/gobject/meson.build b/docs/reference/gobject/meson.build index 221c54a33..fd683aa59 100644 --- a/docs/reference/gobject/meson.build +++ b/docs/reference/gobject/meson.build @@ -34,7 +34,7 @@ if get_option('documentation') and enable_gir custom_target('gobject-docs', input: [ gobject_toml, gobject_gir[0] ], - output: 'gobject', + output: 'gobject-2.0', command: [ gidocgen, 'generate', diff --git a/docs/reference/meson.build b/docs/reference/meson.build index 25904d6a7..65eb83a9e 100644 --- a/docs/reference/meson.build +++ b/docs/reference/meson.build @@ -17,7 +17,7 @@ if get_option('documentation') and enable_gir ] endif -docs_dir = glib_datadir / 'doc' / 'glib-2.0' +docs_dir = glib_datadir / 'doc' subdir('glib') subdir('gmodule')