doc: Port to hotdoc

This commit is contained in:
Thibault Saunier 2018-10-22 08:17:24 +02:00
parent cf6ed5700c
commit 27ba8d24ec
68 changed files with 19530 additions and 17 deletions

1
docs/gst_api_version.in Normal file
View file

@ -0,0 +1 @@
@GST_API_VERSION@

6
docs/index.md Normal file
View file

@ -0,0 +1,6 @@
---
short-description: GStreamer Base Plugins API reference.
...
# GStreamer Base Plugins

View file

@ -0,0 +1,5 @@
# Allocators Library
This library should be linked to by getting cflags and libs from
gstreamer-plugins-base-{{ gst_api_version.md }}.pc and adding
-lgstallocators-{{ gst_api_version.md }} to the library flags.

View file

@ -0,0 +1 @@
gi-index

8
docs/libs/app/index.md Normal file
View file

@ -0,0 +1,8 @@
# App Library
This library should be linked to by getting cflags and libs from
`gstreamer-plugins-base-{{ gst_api_version.md }}pc` and adding
-lgstapp-{{ gst_api_version.md }} to the library flags.
To use it the functionality, insert an `appsrc` or `appsink` element
into a pipeline and call the appropriate functions on the element.

View file

@ -0,0 +1 @@
gi-index

6
docs/libs/audio/index.md Normal file
View file

@ -0,0 +1,6 @@
# Audio Library
This library should be linked to by getting cflags and libs from
`gstreamer-plugins-base-{{ gst_api_version.md }}.pc` and adding
`-lgstaudio-{{ gst_api_version.md }}` to the library flags.

View file

@ -0,0 +1 @@
gi-index

View file

@ -0,0 +1 @@
gi-index

8
docs/libs/fft/index.md Normal file
View file

@ -0,0 +1,8 @@
# FFT Library
The gstfft library is based on
[kissfft](http://sourceforge.net/projects/kissfft) by Mark Borgerding.
This library should be linked to by getting cflags and libs from
`gstreamer-plugins-base-{{ gst_api_version.md }}.pc` and adding
`-lgstfft-{{ gst_api_version.md }}` to the library flags.

View file

@ -0,0 +1 @@
gi-index

View file

@ -0,0 +1,7 @@
# Base Utils Library
This library should be linked to by getting cflags and libs from
`gstreamer-plugins-base-{{ gst_api_version.md }}.pc` and adding
`-lgstpbutils-{{ gst_api_version.md }}` to the library
flags.

View file

@ -0,0 +1,3 @@
gi-index
pbutils.h
encoding-profile.h

5
docs/libs/riff/index.md Normal file
View file

@ -0,0 +1,5 @@
# Riff Media Library
This library should be linked to by getting cflags and libs from
`gstreamer-plugins-base-{{ gst_api_version.md }}.pc` and adding
`-lgstriff-{{ gst_api_version.md }}` to the library flags.

View file

@ -0,0 +1 @@
c-index

5
docs/libs/rtp/index.md Normal file
View file

@ -0,0 +1,5 @@
# RTP Library
This library should be linked to by getting cflags and libs from
`gstreamer-plugins-base-{{ gst_api_version.md }}.pc` and adding
`-lgstrtp-{{ gst_api_version.md }}` to the library flags.

View file

@ -0,0 +1 @@
gi-index

5
docs/libs/rtsp/index.md Normal file
View file

@ -0,0 +1,5 @@
# RTSP Library
This library should be linked to by getting cflags and libs from
`gstreamer-plugins-base-{{ gst_api_version.md }}.pc` and adding
`-lgstrtsp-{{ gst_api_version.md }}` to the library flags.

View file

@ -0,0 +1 @@
gi-index

6
docs/libs/sdp/index.md Normal file
View file

@ -0,0 +1,6 @@
# SDP Library
This library should be linked to by getting cflags and libs from
`gstreamer-plugins-base-{{ gst_api_version.md }}.pc` and adding
`-lgstsdp-{{ gst_api_version.md }}` to the library flags.

View file

@ -0,0 +1 @@
gi-index

6
docs/libs/tag/index.md Normal file
View file

@ -0,0 +1,6 @@
# Tag Support Library
This library should be linked to by getting cflags and libs from
`gstreamer-plugins-base-{{ gst_api_version.md }}.pc` and adding
`-lgsttag-{{ gst_api_version.md }}` to the library flags.

View file

@ -0,0 +1 @@
gi-index

5
docs/libs/video/index.md Normal file
View file

@ -0,0 +1,5 @@
# Video Library
This library should be linked to by getting cflags and libs from
`gstreamer-plugins-base-{{ gst_api_version.md }}.pc` and adding
`-lgstvideo-{{ gst_api_version.md }}` to the library flags.

View file

@ -0,0 +1 @@
gi-index

173
docs/meson.build Normal file
View file

@ -0,0 +1,173 @@
build_hotdoc = false
if meson.is_cross_build()
if get_option('doc').enabled()
error('Documentation enabled but building the doc while cross building is not supported yet.')
endif
message('Documentation not built as building it while cross building is not supported yet.')
subdir_done()
endif
required_hotdoc_extensions = ['gi-extension', 'gst-extension']
if gst_dep.type_name() == 'internal'
gst_proj = subproject('gstreamer')
plugins_cache_generator = gst_proj.get_variable('plugins_cache_generator')
else
plugins_cache_generator = find_program(join_paths(gst_dep.get_pkgconfig_variable('libexecdir'), 'gstreamer-' + api_version, 'gst-plugins-doc-cache-generator'),
required: false)
endif
plugins_cache = join_paths(meson.current_source_dir(), 'plugins', 'gst_plugins_cache.json')
if plugins_cache_generator.found()
plugins_doc_dep = custom_target('base-plugins-doc-cache',
build_by_default: true,
command: [plugins_cache_generator, plugins_cache, '@OUTPUT@', '@INPUT@'],
input: plugins,
output: 'gst_plugins_cache.json',
)
else
warning('GStreamer plugin inspector for documentation not found, can\'t update the cache')
endif
hotdoc_p = find_program('hotdoc', required: get_option('doc'))
if not hotdoc_p.found()
message('Hotdoc not found, not building the documentation')
subdir_done()
endif
hotdoc = import('hotdoc')
foreach extension: required_hotdoc_extensions
if not hotdoc.has_extensions(extension)
if get_option('doc').enabled()
error('Documentation enabled but @0@ missing'.format(extension))
endif
message('@0@ extension not found, not building documentation'.format(extension))
subdir_done()
endif
endforeach
if not build_gir
if get_option('doc').enabled()
error('Documentation enabled but introspection not built.')
endif
message('Introspection not built, can\'t build the documentation')
subdir_done()
endif
build_hotdoc = true
docconf = configuration_data()
docconf.set('GST_API_VERSION', api_version)
version_entities = configure_file(input : 'version.in',
output : 'gst_api_version.md',
configuration : docconf)
libs_excludes = []
foreach h: ['pbutils-private.h', 'gsttageditingprivate.h', 'id3v2.h',
'kiss_fft_f32.h', 'kiss_fft_f64.h', 'kiss_fftr_f32.h', 'kiss_fftr_f64.h',
'kiss_fftr_s16.h', 'kiss_fftr_s32.h', 'kiss_fft_s16.h', 'kiss_fft_s32.h',
'_kiss_fft_guts_f32.h', '_kiss_fft_guts_f64.h', '_kiss_fft_guts_s16.h',
'_kiss_fft_guts_s16.h', '_kiss_fft_guts_s32.h', '_kiss_fft_guts_s32.h',
'pbutils-marshal.h', 'audio-resampler-private.h', '*orc-dist.*',
'*-neon.h', 'audio-resampler-macros.[ch]', '*-prelude.h'
]
libs_excludes += [join_paths(meson.current_source_dir(), '..', 'gst-libs/gst/*/', h)]
endforeach
libs = [
['allocators', allocators_gir, allocators_dep],
['app', app_gir, app_dep],
['audio', audio_gir, audio_dep],
# FIXME! ['fft', fft_gir, fft_dep],
['pbutils', pbutils_gir, pbutils_dep],
['rtp', rtp_gir, rtp_dep],
['rtsp', rtsp_gir, rtsp_dep],
['sdp', sdp_gir, sdp_dep],
['tag', tag_gir, tag_dep],
['video', video_gir, video_dep],
]
if build_gstgl
libs + [['gl', gl_gir, gstgl_dep]]
endif
libs_doc = []
foreach lib: libs
name = lib[0]
gir = lib[1]
deps = [lib[2], gir]
libs_doc += [hotdoc.generate_doc('gst-plugins-base-' + name,
project_version: api_version,
gi_c_sources: [join_paths('../gst-libs/gst', name, '*.[hc]')],
gi_sources: gir[0].full_path(),
gi_c_source_filters: libs_excludes,
gi_c_source_roots: [join_paths(meson.current_source_dir(), '../gst-libs/gst/' + name), ],
sitemap: 'libs/' + name + '/sitemap.txt',
index: 'libs/' + name + '/index.md',
gi_index: 'libs/' + name + '/index.md',
gi_smart_index: true,
gi_order_generated_subpages: true,
dependencies: deps,
install: false,
)]
endforeach
if not hotdoc.has_extensions('c-extension')
if get_option('doc').enabled()
error('Documentation enabled but c-extension missing')
endif
message('c-extension not found, not building documentation')
else
libs_doc += [hotdoc.generate_doc('gst-plugins-base-riff',
project_version: api_version,
c_sources: ['../gst-libs/gst/riff/*.[hc]'],
c_source_filters: libs_excludes,
sitemap: 'libs/riff/sitemap.txt',
index: 'libs/riff/index.md',
c_index: 'libs/riff/index.md',
c_smart_index: true,
c_order_generated_subpages: true,
dependencies: [gst_base_dep, riff_dep],
install: false,
disable_incremental_build: true,
)]
endif
plugins_doc = []
sitemap = 'all_index.md\n'
list_plugin_res = run_command(python3, '-c',
'''
import sys
import json
with open("@0@") as f:
print(':'.join(json.load(f).keys()), end='')
'''.format(plugins_cache))
assert(list_plugin_res.returncode() == 0,
'Could not list plugins from @0@\n@1@\n@1@'.format(plugins_cache, list_plugin_res.stdout(), list_plugin_res.stderr()))
foreach plugin_name: list_plugin_res.stdout().split(':')
plugins_doc += [hotdoc.generate_doc(plugin_name,
project_version: api_version,
sitemap: 'plugins/sitemap.txt',
index: 'plugins/index.md',
gst_index: 'plugins/index.md',
gst_smart_index: true,
gst_c_sources: ['../sys/*/*.[ch]',
'../ext/*/*.[ch]',
'../gst/*/*.[ch]',
],
dependencies: [gst_dep, plugins],
gst_order_generated_subpages: true,
gst_cache_file: plugins_cache,
gst_plugin_name: plugin_name,
)]
sitemap += ' @0@-doc.json\n'.format(plugin_name)
endforeach

View file

@ -0,0 +1,5 @@
---
short-description: Plugins from gst-plugins-base
...
# Plugins

File diff suppressed because one or more lines are too long

0
docs/plugins/index.md Normal file
View file

1
docs/plugins/sitemap.txt Normal file
View file

@ -0,0 +1 @@
gst-index

3
docs/sitemap.txt Normal file
View file

@ -0,0 +1,3 @@
index.md
gst-plugins-base-libs-doc.json
gst-plugins-base-plugins-doc.json

1
docs/version.in Normal file
View file

@ -0,0 +1 @@
@GST_API_VERSION@

View file

@ -19,4 +19,5 @@ if alsa_dep.found()
install_dir : plugins_install_dir,
)
pkgconfig.generate(gstalsa, install_dir : plugins_pkgconfig_install_dir)
plugins += [gstalsa]
endif

View file

@ -38,4 +38,5 @@ if cdparanoia_found
install_dir : plugins_install_dir,
)
pkgconfig.generate(gstcdparanoia, install_dir : plugins_pkgconfig_install_dir)
plugins += [gstcdparanoia]
endif

View file

@ -123,3 +123,4 @@ gstopengl = library('gstopengl',
install_dir : plugins_install_dir)
pkgconfig.generate(gstopengl, install_dir : plugins_pkgconfig_install_dir)
plugins += [gstopengl]

View file

@ -18,4 +18,5 @@ if libvisual_dep.found()
install_dir : plugins_install_dir,
)
pkgconfig.generate(gstlibvisual, install_dir : plugins_pkgconfig_install_dir)
plugins += [gstlibvisual]
endif

View file

@ -24,4 +24,5 @@ if ogg_dep.found()
install_dir : plugins_install_dir,
)
pkgconfig.generate(gstogg, install_dir : plugins_pkgconfig_install_dir)
plugins += [gstogg]
endif

View file

@ -19,4 +19,5 @@ if opus_dep.found()
install_dir : plugins_install_dir,
)
pkgconfig.generate(gstopus, install_dir : plugins_pkgconfig_install_dir)
plugins += [gstopus]
endif

View file

@ -19,4 +19,5 @@ if pango_dep.found()
install_dir : plugins_install_dir,
)
pkgconfig.generate(gstpango, install_dir : plugins_pkgconfig_install_dir)
plugins += [gstpango]
endif

View file

@ -37,8 +37,8 @@
* set up a correct cropping region if the dimensions are not multiples of 16
* pixels.
*
* To control the quality of the encoding, the #GstTheoraEnc::bitrate and
* #GstTheoraEnc::quality properties can be used. These two properties are
* To control the quality of the encoding, the #GstTheoraEnc:bitrate and
* #GstTheoraEnc:quality properties can be used. These two properties are
* mutualy exclusive. Setting the bitrate property will produce a constant
* bitrate (CBR) stream while setting the quality property will produce a
* variable bitrate (VBR) stream.
@ -704,7 +704,7 @@ theora_enc_init_buffer (th_ycbcr_buffer buf, GstVideoFrame * frame)
GstVideoInfo vinfo;
guint i;
/* According to Theora developer Timothy Terriberry, the Theora
/* According to Theora developer Timothy Terriberry, the Theora
* encoder will not use memory outside of pic_width/height, even when
* the frame size is bigger. The values outside this region will be encoded
* to default values.

View file

@ -27,4 +27,5 @@ if theoradec_dep.found() or theoraenc_dep.found()
install_dir : plugins_install_dir,
)
pkgconfig.generate(gsttheora, install_dir : plugins_pkgconfig_install_dir)
plugins += [gsttheora]
endif

View file

@ -40,6 +40,7 @@ if vorbis_dep.found()
install_dir : plugins_install_dir,
)
pkgconfig.generate(gstvorbis, install_dir : plugins_pkgconfig_install_dir)
plugins += [gstvorbis]
endif
if vorbisidec_dep.found()
@ -55,4 +56,5 @@ if vorbisidec_dep.found()
install_dir : plugins_install_dir,
)
pkgconfig.generate(gstivorbisdec, install_dir : plugins_pkgconfig_install_dir)
plugins += [gstivorbisdec]
endif

View file

@ -22,6 +22,11 @@
* SECTION:encoding-profile
* @title: GstEncodingProfile
* @short_description: Encoding profile library
* @symbols:
* - GstEncodingProfile
* - GstEncodingContainerProfile
* - GstEncodingVideoProfile
* - GstEncodingAudioProfile
*
* Functions to create and handle encoding profiles.
*

View file

@ -28,3 +28,4 @@ adder = library('gstadder',
install_dir : plugins_install_dir,
)
pkgconfig.generate(adder, install_dir : plugins_pkgconfig_install_dir)
plugins += [adder]

View file

@ -7,3 +7,5 @@ gstapp_plugin = library('gstapp',
install_dir : plugins_install_dir,
)
pkgconfig.generate(gstapp_plugin, install_dir : plugins_pkgconfig_install_dir)
plugins += [gstapp_plugin]

View file

@ -12,3 +12,4 @@ gstaudioconvert = library('gstaudioconvert',
install_dir : plugins_install_dir,
)
pkgconfig.generate(gstaudioconvert, install_dir : plugins_pkgconfig_install_dir)
plugins += [gstaudioconvert]

View file

@ -31,3 +31,4 @@ gstaudiomixer = library('gstaudiomixer',
install_dir : plugins_install_dir,
)
pkgconfig.generate(gstaudiomixer, install_dir : plugins_pkgconfig_install_dir)
plugins += [gstaudiomixer]

View file

@ -7,3 +7,4 @@ audiorate = library('gstaudiorate',
install_dir : plugins_install_dir,
)
pkgconfig.generate(audiorate, install_dir : plugins_pkgconfig_install_dir)
plugins += [audiorate]

View file

@ -9,3 +9,4 @@ audioresample = library('gstaudioresample',
install_dir : plugins_install_dir,
)
pkgconfig.generate(audioresample, install_dir : plugins_pkgconfig_install_dir)
plugins += [audioresample]

View file

@ -7,3 +7,4 @@ audiotest = library('gstaudiotestsrc',
install_dir : plugins_install_dir,
)
pkgconfig.generate(audiotest, install_dir : plugins_pkgconfig_install_dir)
plugins += [audiotest]

View file

@ -31,3 +31,4 @@ gstcompositor = library('gstcompositor',
install_dir : plugins_install_dir,
)
pkgconfig.generate(gstcompositor, install_dir : plugins_pkgconfig_install_dir)
plugins += [gstcompositor]

View file

@ -13,3 +13,4 @@ gstencoding = library('gstencoding',
install_dir : plugins_install_dir,
)
pkgconfig.generate(gstencoding, install_dir : plugins_pkgconfig_install_dir)
plugins += [gstencoding]

View file

@ -16,3 +16,4 @@ gstgio = library('gstgio',
install_dir : plugins_install_dir,
)
pkgconfig.generate(gstgio, install_dir : plugins_pkgconfig_install_dir)
plugins += [gstgio]

View file

@ -11,3 +11,4 @@ gstpbtypes = library('gstpbtypes',
install_dir : plugins_install_dir,
)
pkgconfig.generate(gstpbtypes, install_dir : plugins_pkgconfig_install_dir)
plugins += [gstpbtypes]

View file

@ -27,3 +27,4 @@ gstplayback = library('gstplayback',
install_dir : plugins_install_dir,
)
pkgconfig.generate(gstplayback, install_dir : plugins_pkgconfig_install_dir)
plugins += [gstplayback]

View file

@ -16,4 +16,5 @@ gstrawparse = library('gstrawparse',
install_dir : plugins_install_dir,
)
pkgconfig.generate(gstrawparse, install_dir : plugins_pkgconfig_install_dir)
plugins += [gstrawparse]

View file

@ -16,3 +16,4 @@ gstsubparse = library('gstsubparse',
install_dir : plugins_install_dir,
)
pkgconfig.generate(gstsubparse, install_dir : plugins_pkgconfig_install_dir)
plugins += [gstsubparse]

View file

@ -22,3 +22,4 @@ gsttcp = library('gsttcp',
install_dir : plugins_install_dir,
)
pkgconfig.generate(gsttcp, install_dir : plugins_pkgconfig_install_dir)
plugins += [gsttcp]

View file

@ -7,3 +7,4 @@ gsttypefind = library('gsttypefindfunctions',
install_dir : plugins_install_dir,
)
pkgconfig.generate(gsttypefind, install_dir : plugins_pkgconfig_install_dir)
plugins += [gsttypefind]

View file

@ -11,3 +11,4 @@ gstvideoconvert = library('gstvideoconvert',
install_dir : plugins_install_dir,
)
pkgconfig.generate(gstvideoconvert, install_dir : plugins_pkgconfig_install_dir)
plugins += [gstvideoconvert]

View file

@ -7,3 +7,4 @@ gstvideorate = library('gstvideorate',
install_dir : plugins_install_dir,
)
pkgconfig.generate(gstvideorate, install_dir : plugins_pkgconfig_install_dir)
plugins += [gstvideorate]

View file

@ -11,3 +11,4 @@ gstvideoscale = library('gstvideoscale',
install_dir : plugins_install_dir,
)
pkgconfig.generate(gstvideoscale, install_dir : plugins_pkgconfig_install_dir)
plugins += [gstvideoscale]

View file

@ -28,3 +28,4 @@ gstvideotestsrc = library('gstvideotestsrc',
install_dir : plugins_install_dir,
)
pkgconfig.generate(gstvideotestsrc, install_dir : plugins_pkgconfig_install_dir)
plugins += [gstvideotestsrc]

View file

@ -27,3 +27,4 @@ gstvolume = library('gstvolume', 'gstvolume.c', orc_c, orc_h,
install_dir : plugins_install_dir,
)
pkgconfig.generate(gstvolume, install_dir : plugins_pkgconfig_install_dir)
plugins += [gstvolume]

View file

@ -1,6 +1,6 @@
project('gst-plugins-base', 'c',
version : '1.17.0.1',
meson_version : '>= 0.47',
meson_version : '>= 0.48',
default_options : [ 'warning_level=1',
'buildtype=debugoptimized' ])
@ -32,6 +32,7 @@ libversion = '@0@.@1@.0'.format(soversion, curversion)
osxversion = curversion + 1
plugins_install_dir = join_paths(get_option('libdir'), 'gstreamer-1.0')
plugins = []
cc = meson.get_compiler('c')
host_system = host_machine.system()
@ -371,6 +372,7 @@ if get_option('default_library') == 'shared'
plugins_pkgconfig_install_dir = disabler()
endif
python3 = import('python').find_installation()
subdir('gst-libs')
subdir('gst')
subdir('ext')
@ -380,25 +382,14 @@ if not get_option('tools').disabled()
endif
subdir('tests')
subdir('pkgconfig')
# xgettext is optional (on Windows for instance)
if find_program('xgettext', required : get_option('nls')).found()
core_conf.set('ENABLE_NLS', 1)
subdir('po')
endif
if build_machine.system() == 'windows'
message('Disabling gtk-doc while building on Windows')
else
if find_program('gtkdoc-scan', required : get_option('gtk_doc')).found()
subdir('docs')
else
message('Not building documentation as gtk-doc was not found')
endif
endif
subdir('docs')
# Use core_conf after all subdirs have set values
configure_file(output : 'config.h', configuration : core_conf)
python3 = import('python').find_installation()
run_command(python3, '-c', 'import shutil; shutil.copy("hooks/pre-commit.hook", ".git/hooks/pre-commit")')

View file

@ -69,7 +69,6 @@ option('xvideo', type : 'feature', value : 'auto', description : 'X11 XVideo xvi
option('examples', type : 'feature', value : 'auto', yield : true)
option('tests', type : 'feature', value : 'auto', yield : true)
option('tools', type : 'feature', value : 'auto', yield : true)
option('gtk_doc', type : 'feature', value : 'auto', yield : true, description : 'Build API documentation with gtk-doc')
option('introspection', type : 'feature', value : 'auto', yield : true, description : 'Generate gobject-introspection bindings')
option('nls', type : 'feature', value : 'auto', yield: true, description : 'Enable native language support (translations)')
option('orc', type : 'feature', value : 'auto', yield : true)
@ -85,3 +84,5 @@ option('package-name', type : 'string', yield : true,
description : 'package name to use in plugins')
option('package-origin', type : 'string', value : 'Unknown package origin', yield : true,
description : 'package origin URL to use in plugins')
option('doc', type : 'feature', value : 'auto', yield: true,
description: 'Enable documentation.')

View file

@ -7,3 +7,4 @@ gstximage = library('gstximagesink',
install_dir : plugins_install_dir,
)
pkgconfig.generate(gstximage, install_dir : plugins_pkgconfig_install_dir)
plugins += [gstximage]

View file

@ -19,4 +19,5 @@ if xvideo_dep.found()
install_dir : plugins_install_dir,
)
pkgconfig.generate(gstxvimage, install_dir : plugins_pkgconfig_install_dir)
plugins += [gstxvimage]
endif