subprojects/gst-plugins-base/docs/meson.build

   1 build_hotdoc = false
   2
   3 if meson.is_cross_build()
   4     if get_option('doc').enabled()
   5         error('Documentation enabled but building the doc while cross building is not supported yet.')
   6     endif
   7
   8     message('Documentation not built as building it while cross building is not supported yet.')
   9     subdir_done()
  10 endif
  11
  12 if static_build
  13     if get_option('doc').enabled()
  14         error('Documentation enabled but not supported when building statically.')
  15     endif
  16
  17     message('Building statically, can\'t build the documentation')
  18     subdir_done()
  19 endif
  20
  21 if not build_gir
  22     if get_option('doc').enabled()
  23         error('Documentation enabled but introspection not built.')
  24     endif
  25
  26     message('Introspection not built, won\'t build documentation requiring it')
  27     subdir_done()
  28 endif
  29
  30
  31 required_hotdoc_extensions = ['gi-extension', 'gst-extension']
  32 if gst_dep.type_name() == 'internal'
  33     gst_proj = subproject('gstreamer')
  34     plugins_cache_generator = gst_proj.get_variable('plugins_cache_generator')
  35 else
  36     plugins_cache_generator = find_program(join_paths(gst_dep.get_variable('libexecdir'), 'gstreamer-' + api_version, 'gst-plugins-doc-cache-generator'),
  37         required: false)
  38 endif
  39
  40 plugins_cache = join_paths(meson.current_source_dir(), 'plugins', 'gst_plugins_cache.json')
  41 if plugins.length() == 0
  42     message('All base plugins have been disabled')
  43 elif plugins_cache_generator.found()
  44     gst_plugins_doc_dep = custom_target('base-plugins-doc-cache',
  45         command: [plugins_cache_generator, plugins_cache, '@OUTPUT@', '@INPUT@'],
  46         input: plugins,
  47         output: 'gst_plugins_cache.json',
  48         build_always_stale: true,
  49     )
  50 else
  51     warning('GStreamer plugin inspector for documentation not found, can\'t update the cache')
  52 endif
  53
  54 hotdoc_p = find_program('hotdoc', required: get_option('doc'))
  55 if not hotdoc_p.found()
  56     message('Hotdoc not found, not building the documentation')
  57     subdir_done()
  58 endif
  59
  60 hotdoc_req = '>= 0.11.0'
  61 hotdoc_version = run_command(hotdoc_p, '--version', check: false).stdout()
  62 if not hotdoc_version.version_compare(hotdoc_req)
  63     if get_option('doc').enabled()
  64         error('Hotdoc version @0@ not found, got @1@'.format(hotdoc_req, hotdoc_version))
  65     else
  66         message('Hotdoc version @0@ not found, got @1@'.format(hotdoc_req, hotdoc_version))
  67         subdir_done()
  68     endif
  69 endif
  70
  71 hotdoc = import('hotdoc')
  72 foreach extension: required_hotdoc_extensions
  73     if not hotdoc.has_extensions(extension)
  74         if get_option('doc').enabled()
  75             error('Documentation enabled but @0@ missing'.format(extension))
  76         endif
  77
  78         message('@0@ extension not found, not building documentation'.format(extension))
  79         subdir_done()
  80     endif
  81 endforeach
  82
  83 build_hotdoc = true
  84 docconf = configuration_data()
  85 docconf.set('GST_API_VERSION', api_version)
  86
  87 version_entities = configure_file(input : 'version.in',
  88     output : 'gst_api_version.md',
  89     configuration : docconf)
  90
  91 libs_excludes = []
  92 foreach h: ['pbutils-private.h', 'gsttageditingprivate.h', 'id3v2.h',
  93   'kiss_fft_f32.h', 'kiss_fft_f64.h', 'kiss_fftr_f32.h', 'kiss_fftr_f64.h',
  94   'kiss_fftr_s16.h', 'kiss_fftr_s32.h', 'kiss_fft_s16.h', 'kiss_fft_s32.h',
  95   '_kiss_fft_guts_f32.h', '_kiss_fft_guts_f64.h', '_kiss_fft_guts_s16.h',
  96   '_kiss_fft_guts_s16.h', '_kiss_fft_guts_s32.h', '_kiss_fft_guts_s32.h',
  97   'pbutils-marshal.h', 'audio-resampler-private.h', '*orc-dist.*',
  98   '*-neon.h', 'audio-resampler-macros.[ch]', '*-prelude.h', '*_private.h',
  99   'gstglfuncs.[ch]', 'gstgl_fwd.h'
 100   ]
 101
 102   libs_excludes += [join_paths(meson.current_source_dir(), '..', 'gst-libs/gst/*/', h)]
 103 endforeach
 104
 105 libs = [
 106   ['allocators', allocators_gir, allocators_dep],
 107   ['app', app_gir, app_dep],
 108   ['audio', audio_gir, audio_dep],
 109   # FIXME! ['fft', fft_gir, fft_dep],
 110   ['pbutils', pbutils_gir, pbutils_dep],
 111   ['rtp', rtp_gir, rtp_dep],
 112   ['rtsp', rtsp_gir, rtsp_dep],
 113   ['sdp', sdp_gir, sdp_dep],
 114   ['tag', tag_gir, tag_dep],
 115   ['video', video_gir, video_dep],
 116 ]
 117
 118 if build_gstgl
 119   libs += [['gl', gl_gir, gstgl_dep]]
 120   if enabled_gl_platforms.contains('egl')
 121     libs += [['gl-egl', gl_egl_gir, gstgl_dep, [
 122       join_paths('../gst-libs/gst', 'gl', 'egl', 'gstegl.[ch]'),
 123       join_paths('../gst-libs/gst', 'gl', 'egl', 'gsteglimage.[ch]'),
 124       join_paths('../gst-libs/gst', 'gl', 'egl', 'gstgldisplay_egl.[ch]'),
 125       join_paths('../gst-libs/gst', 'gl', 'egl', 'gstgldisplay_egl_device.[ch]'),
 126       join_paths('../gst-libs/gst', 'gl', 'egl', 'gstglmemoryegl.[ch]'),
 127     ]]]
 128   endif
 129   if enabled_gl_winsys.contains('x11')
 130     libs += [['gl-x11', gl_x11_gir, gstgl_dep, [
 131       join_paths('../gst-libs/gst', 'gl', 'x11', 'gstgldisplay_x11.[ch]'),
 132     ]]]
 133   endif
 134   if enabled_gl_winsys.contains('wayland')
 135     libs += [['gl-wayland', gl_wayland_gir, gstgl_dep, [
 136       join_paths('../gst-libs/gst', 'gl', 'wayland', 'gstgldisplay_wayland.[ch]'),
 137     ]]]
 138   endif
 139 endif
 140
 141 # Used to avoid conflicts with known plugin names
 142 project_names = {
 143   'app': 'applib',
 144   'rtp': 'rtplib',
 145   'rtsp': 'rtsplib',
 146 }
 147
 148 libs_doc = []
 149 foreach lib: libs
 150   name = lib[0]
 151   gir = lib[1]
 152   deps = [lib[2], gir]
 153   extra_sources = []
 154   if lib.length() >= 4
 155     extra_sources = lib[3]
 156   endif
 157   project_name = project_names.get(name, name)
 158   libs_doc += [hotdoc.generate_doc(project_name,
 159       project_version: api_version,
 160       gi_c_sources: [join_paths('../gst-libs/gst', name, '*.[hc]')] + extra_sources,
 161       gi_sources: gir[0].full_path(),
 162       gi_c_source_filters: libs_excludes,
 163       gi_c_source_roots: [join_paths(meson.current_source_dir(), '../gst-libs/gst/' + name), ],
 164       sitemap: 'libs/' + name + '/sitemap.txt',
 165       index: 'libs/' + name + '/index.md',
 166       gi_index: 'libs/' + name + '/index.md',
 167       gi_smart_index: true,
 168       gi_order_generated_subpages: true,
 169       dependencies: deps,
 170       install: false,
 171   )]
 172 endforeach
 173
 174 if not hotdoc.has_extensions('c-extension')
 175     if get_option('doc').enabled()
 176         error('Documentation enabled but c-extension missing')
 177     endif
 178     message('c-extension not found, not building documentation')
 179 else
 180     libs_doc += [hotdoc.generate_doc('riff',
 181         project_version: api_version,
 182         c_sources: ['../gst-libs/gst/riff/*.[hc]'],
 183         c_source_filters: libs_excludes,
 184         sitemap: 'libs/riff/sitemap.txt',
 185         index: 'libs/riff/index.md',
 186         c_index: 'libs/riff/index.md',
 187         c_smart_index: true,
 188         c_order_generated_subpages: true,
 189         dependencies: [gst_base_dep, riff_dep],
 190         install: false,
 191         disable_incremental_build: true,
 192     )]
 193 endif
 194
 195 plugins_doc = []
 196 sitemap = 'all_index.md\n'
 197
 198 list_plugin_res = run_command(python3, '-c',
 199 '''
 200 import sys
 201 import json
 202
 203 with open("@0@") as f:
 204     print(':'.join(json.load(f).keys()), end='')
 205 '''.format(plugins_cache),
 206   check: true)
 207 foreach plugin_name: list_plugin_res.stdout().split(':')
 208     plugins_doc += [hotdoc.generate_doc(plugin_name,
 209         project_version: api_version,
 210         sitemap: 'plugins/sitemap.txt',
 211         index: 'plugins/index.md',
 212         gst_index: 'plugins/index.md',
 213         gst_smart_index: true,
 214         gst_c_sources: [
 215           '../sys/*/*.[ch]',
 216           '../ext/*/*.[cmh]',
 217           '../gst/*/*.[ch]',
 218         ],
 219         dependencies: [gst_dep],
 220         gst_order_generated_subpages: true,
 221         gst_cache_file: plugins_cache,
 222         gst_plugin_name: plugin_name,
 223     )]
 224     sitemap += '        @0@-doc.json\n'.format(plugin_name)
 225 endforeach