gnome: add support for `module_version`

gtk-doc for autotools has the concept of module version, that is used to define
the module install path and the devhelp2 basename.

Add a `module_version` parameter to gnome.gtkdoc to replicate the same behavior.
Updated the test checking that the install_dir is properly computed (if not
passed), and that the .devhelp2 file has proper name.

https://gitlab.gnome.org/GNOME/gtk-doc/blob/GTK_DOC_1_29/buildsystems/autotools/gtk-doc.make#L269

docs/markdown/Gnome-module.md

@@ -333,6 +333,7 @@ of the module.
 * `main_xml`: specifies the main XML file
 * `main_sgml`: equal to `main_xml`
 * `mkdb_args`: a list of arguments to pass to `gtkdoc-mkdb`
+* `module_version`: the version of the module, affects the installed location and the devhelp2 file location
 * `scan_args`: a list of arguments to pass to `gtkdoc-scan`
 * `scanobjs_args`: a list of arguments to pass to `gtkdoc-scangobj`
 * `c_args`: (*Added 0.48.0*) additional compile arguments to pass

mesonbuild/modules/gnome.py

@@ -883,12 +883,13 @@ This will become a hard error in the future.''')
         return ModuleReturnValue(None, rv)
 
     @FeatureNewKwargs('gnome.gtkdoc', '0.48.0', ['c_args'])
+    @FeatureNewKwargs('gnome.gtkdoc', '0.48.0', ['module_version'])
     @FeatureNewKwargs('gnome.gtkdoc', '0.37.0', ['namespace', 'mode'])
     @permittedKwargs({'main_xml', 'main_sgml', 'src_dir', 'dependencies', 'install',
                       'install_dir', 'scan_args', 'scanobjs_args', 'gobject_typesfile',
                       'fixxref_args', 'html_args', 'html_assets', 'content_files',
                       'mkdb_args', 'ignore_headers', 'include_directories',
-                      'namespace', 'mode', 'expand_content_files'})
+                      'namespace', 'mode', 'expand_content_files', 'module_version'})
     def gtkdoc(self, state, args, kwargs):
         if len(args) != 1:
             raise MesonException('Gtkdoc must have one positional argument.')
@@ -903,11 +904,14 @@ This will become a hard error in the future.''')
         main_xml = kwargs.get('main_xml', '')
         if not isinstance(main_xml, str):
             raise MesonException('Main xml keyword argument must be a string.')
+        moduleversion = kwargs.get('module_version', '')
+        if not isinstance(moduleversion, str):
+            raise MesonException('Module version keyword argument must be a string.')
         if main_xml != '':
             if main_file != '':
                 raise MesonException('You can only specify main_xml or main_sgml, not both.')
             main_file = main_xml
-        targetname = modulename + '-doc'
+        targetname = modulename + ('-' + moduleversion if moduleversion else '') + '-doc'
         command = state.environment.get_build_command()
 
         namespace = kwargs.get('namespace', '')
@@ -938,6 +942,7 @@ This will become a hard error in the future.''')
                 '--headerdirs=' + '@@'.join(header_dirs),
                 '--mainfile=' + main_file,
                 '--modulename=' + modulename,
+                '--moduleversion=' + moduleversion,
                 '--mode=' + mode]
         if namespace:
             args.append('--namespace=' + namespace)

mesonbuild/scripts/gtkdochelper.py

@@ -28,6 +28,7 @@ parser.add_argument('--subdir', dest='subdir')
 parser.add_argument('--headerdirs', dest='headerdirs')
 parser.add_argument('--mainfile', dest='mainfile')
 parser.add_argument('--modulename', dest='modulename')
+parser.add_argument('--moduleversion', dest='moduleversion')
 parser.add_argument('--htmlargs', dest='htmlargs', default='')
 parser.add_argument('--scanargs', dest='scanargs', default='')
 parser.add_argument('--scanobjsargs', dest='scanobjsargs', default='')
@@ -73,7 +74,7 @@ def gtkdoc_run_check(cmd, cwd, library_paths=None):
         print(out)
 
 def build_gtkdoc(source_root, build_root, doc_subdir, src_subdirs,
-                 main_file, module,
+                 main_file, module, module_version,
                  html_args, scan_args, fixxref_args, mkdb_args,
                  gobject_typesfile, scanobjs_args, run, ld, cc, ldflags, cflags,
                  html_assets, content_files, ignore_headers, namespace,
@@ -191,7 +192,7 @@ def build_gtkdoc(source_root, build_root, doc_subdir, src_subdirs,
     else:
         mkhtml_cmd.append('%s-docs.xml' % module)
     # html gen must be run in the HTML dir
-    gtkdoc_run_check(mkhtml_cmd, os.path.join(abs_out, 'html'))
+    gtkdoc_run_check(mkhtml_cmd, htmldir)
 
     # Fix cross-references in HTML files
     fixref_cmd = ['gtkdoc-fixxref',
@@ -199,6 +200,10 @@ def build_gtkdoc(source_root, build_root, doc_subdir, src_subdirs,
                   '--module-dir=html'] + fixxref_args
     gtkdoc_run_check(fixref_cmd, abs_out)
 
+    if module_version:
+        shutil.move(os.path.join(htmldir, '{}.devhelp2'.format(module)),
+                    os.path.join(htmldir, '{}-{}.devhelp2'.format(module, module_version)))
+
 def install_gtkdoc(build_root, doc_subdir, install_prefix, datadir, module):
     source = os.path.join(build_root, doc_subdir, 'html')
     final_destination = os.path.join(install_prefix, datadir, module)
@@ -234,6 +239,7 @@ def run(args):
         options.headerdirs.split('@@'),
         options.mainfile,
         options.modulename,
+        options.moduleversion,
         htmlargs,
         scanargs,
         fixxrefargs,
@@ -255,7 +261,12 @@ def run(args):
     if 'MESON_INSTALL_PREFIX' in os.environ:
         destdir = os.environ.get('DESTDIR', '')
         install_prefix = destdir_join(destdir, os.environ['MESON_INSTALL_PREFIX'])
-        install_dir = options.install_dir if options.install_dir else options.modulename
+        if options.install_dir:
+            install_dir = options.install_dir
+        else:
+            install_dir = options.modulename
+            if options.moduleversion:
+                install_dir += '-' + options.moduleversion
         if os.path.isabs(install_dir):
             install_dir = destdir_join(destdir, install_dir)
         install_gtkdoc(options.builddir,

test cases/frameworks/10 gtk-doc/doc/meson.build

@@ -16,3 +16,18 @@ gnome.gtkdoc('foobar2',
   content_files : [docbook, version_xml],
   install : true,
   install_dir : 'foobar2')
+
+gnome.gtkdoc('foobar',
+  module_version : '3.0',
+  src_dir : inc,
+  main_sgml : 'foobar-docs.sgml',
+  content_files : [docbook, version_xml],
+  install : true)
+
+gnome.gtkdoc('foobar2',
+  module_version : '3.0',
+  src_dir : inc,
+  main_sgml : 'foobar-docs.sgml',
+  content_files : [docbook, version_xml],
+  install : true,
+  install_dir : 'foobar3')

test cases/frameworks/10 gtk-doc/installed_files.txt

@@ -27,3 +27,31 @@ usr/share/gtk-doc/html/foobar2/right-insensitive.png
 usr/share/gtk-doc/html/foobar2/style.css
 usr/share/gtk-doc/html/foobar2/up.png
 usr/share/gtk-doc/html/foobar2/up-insensitive.png
+usr/share/gtk-doc/html/foobar-3.0/BAR.html
+usr/share/gtk-doc/html/foobar-3.0/foobar-3.0.devhelp2
+usr/share/gtk-doc/html/foobar-3.0/foobar.html
+usr/share/gtk-doc/html/foobar-3.0/foobar-foo.html
+usr/share/gtk-doc/html/foobar-3.0/foobar-foo-version.html
+usr/share/gtk-doc/html/foobar-3.0/home.png
+usr/share/gtk-doc/html/foobar-3.0/index.html
+usr/share/gtk-doc/html/foobar-3.0/left.png
+usr/share/gtk-doc/html/foobar-3.0/left-insensitive.png
+usr/share/gtk-doc/html/foobar-3.0/right.png
+usr/share/gtk-doc/html/foobar-3.0/right-insensitive.png
+usr/share/gtk-doc/html/foobar-3.0/style.css
+usr/share/gtk-doc/html/foobar-3.0/up.png
+usr/share/gtk-doc/html/foobar-3.0/up-insensitive.png
+usr/share/gtk-doc/html/foobar3/BAR.html
+usr/share/gtk-doc/html/foobar3/foobar2-3.0.devhelp2
+usr/share/gtk-doc/html/foobar3/foobar.html
+usr/share/gtk-doc/html/foobar3/foobar2-foo.html
+usr/share/gtk-doc/html/foobar3/foobar2-foo-version.html
+usr/share/gtk-doc/html/foobar3/home.png
+usr/share/gtk-doc/html/foobar3/index.html
+usr/share/gtk-doc/html/foobar3/left.png
+usr/share/gtk-doc/html/foobar3/left-insensitive.png
+usr/share/gtk-doc/html/foobar3/right.png
+usr/share/gtk-doc/html/foobar3/right-insensitive.png
+usr/share/gtk-doc/html/foobar3/style.css
+usr/share/gtk-doc/html/foobar3/up.png
+usr/share/gtk-doc/html/foobar3/up-insensitive.png