Commit 47a49f33 authored by Thibault Saunier's avatar Thibault Saunier

docs: Build documentation with hotdoc

parent 5a2b9357
Pipeline #36616 failed with stages
in 6 minutes and 26 seconds
...@@ -95,3 +95,6 @@ Build ...@@ -95,3 +95,6 @@ Build
# Meson # Meson
/build /build
/subprojects /subprojects
# hotdoc
docs/hotdoc/libs/generated_sitemap.txt
DISTCHECK_CONFIGURE_FLAGS=--enable-gtk-doc
SUBDIRS = \ SUBDIRS = \
gst-libs gst sys ext pkgconfig \ gst-libs gst sys ext pkgconfig \
m4 common docs tests po tools m4 common tests po tools
DIST_SUBDIRS = \ DIST_SUBDIRS = \
gst gst-libs sys ext pkgconfig \ gst gst-libs sys ext pkgconfig \
m4 common docs tests po tools m4 common tests po tools
EXTRA_DIST = \ EXTRA_DIST = \
depcomp \ depcomp \
...@@ -46,7 +44,6 @@ CRUFT_FILES = \ ...@@ -46,7 +44,6 @@ CRUFT_FILES = \
$(top_builddir)/gst-plugins-bad.spec \ $(top_builddir)/gst-plugins-bad.spec \
$(top_builddir)/common/shave \ $(top_builddir)/common/shave \
$(top_builddir)/common/shave-libtool \ $(top_builddir)/common/shave-libtool \
$(top_builddir)/docs/plugins/xml/plugin-sdp.xml \
$(top_builddir)/ext/alsaspdif/.libs/*.{so,dll,DLL,dylib} \ $(top_builddir)/ext/alsaspdif/.libs/*.{so,dll,DLL,dylib} \
$(top_builddir)/ext/gtk/.libs/libgstgtksink.so \ $(top_builddir)/ext/gtk/.libs/libgstgtksink.so \
$(top_builddir)/ext/gtk/.libs/libgstgtk.so \ $(top_builddir)/ext/gtk/.libs/libgstgtk.so \
...@@ -102,7 +99,6 @@ CRUFT_FILES = \ ...@@ -102,7 +99,6 @@ CRUFT_FILES = \
$(top_builddir)/tests/icles/equalizer-test $(top_builddir)/tests/icles/equalizer-test
CRUFT_DIRS = \ CRUFT_DIRS = \
$(top_srcdir)/docs/plugins/tmpl \
$(top_srcdir)/gst/aacparse \ $(top_srcdir)/gst/aacparse \
$(top_srcdir)/gst/amrparse \ $(top_srcdir)/gst/amrparse \
$(top_srcdir)/gst/audiomixer \ $(top_srcdir)/gst/audiomixer \
......
...@@ -138,10 +138,6 @@ AM_CONDITIONAL(HAVE_VALGRIND, test ! "x$VALGRIND_PATH" = "xno") ...@@ -138,10 +138,6 @@ AM_CONDITIONAL(HAVE_VALGRIND, test ! "x$VALGRIND_PATH" = "xno")
dnl check for gobject-introspection dnl check for gobject-introspection
GOBJECT_INTROSPECTION_CHECK([1.31.1]) GOBJECT_INTROSPECTION_CHECK([1.31.1])
dnl check for documentation tools
GTK_DOC_CHECK([1.12])
AG_GST_PLUGIN_DOCS([1.12])
dnl *** checks for libraries *** dnl *** checks for libraries ***
dnl check for libm, for sin() etc. dnl check for libm, for sin() etc.
...@@ -2698,10 +2694,6 @@ ext/webrtcdsp/Makefile ...@@ -2698,10 +2694,6 @@ ext/webrtcdsp/Makefile
ext/wpe/Makefile ext/wpe/Makefile
ext/ttml/Makefile ext/ttml/Makefile
po/Makefile.in po/Makefile.in
docs/Makefile
docs/plugins/Makefile
docs/libs/Makefile
docs/version.entities
pkgconfig/Makefile pkgconfig/Makefile
pkgconfig/gstreamer-plugins-bad.pc pkgconfig/gstreamer-plugins-bad.pc
pkgconfig/gstreamer-plugins-bad-uninstalled.pc pkgconfig/gstreamer-plugins-bad-uninstalled.pc
......
if ENABLE_GTK_DOC
if ENABLE_PLUGIN_DOCS
PLUGIN_DOCS_DIRS = plugins
else
PLUGIN_DOCS_DIRS =
endif
else
PLUGIN_DOCS_DIRS = plugins
endif
SUBDIRS = libs $(PLUGIN_DOCS_DIRS)
DIST_SUBDIRS = libs plugins
EXTRA_DIST = \
random/ChangeLog-0.8 \
version.entities.in
upload:
@if test "x$(SUBDIRS)" != x; then for a in $(SUBDIRS); do cd $$a; make upload; cd ..; done; fi
@GST_API_VERSION@
---
short-description: GStreamer Bad Plugins API reference.
...
# GStreamer Bad Plugins
Makefile
Makefile.in
*-decl.txt
*-decl-list.txt
*-undocumented.txt
*-undeclared.txt
*-unused.txt
*.bak
*.args
*.hierarchy
*.interfaces
*.prerequisites
*.signals
gst-plugins-bad-libs.args.new
gst-plugins-bad-libs.signals.new
tmpl
xml
html
gst-plugins-bad-libs-scan
gst-plugins-bad-libs-scan.c
*-registry.*
*.stamp
## Process this file with automake to produce Makefile.in
# FIXME: fix the docs then remove this variable
DOCS_ARE_INCOMPLETE_PLEASE_FIXME=yespleasedo
# The name of the module, e.g. 'glib'.
#DOC_MODULE=gst-plugins-libs-@GST_API_VERSION@
DOC_MODULE=gst-plugins-bad-libs
# for upload-doc.mak
DOC=gst-plugins-bad-libs
FORMATS=html
html: html-build.stamp
include $(top_srcdir)/common/upload-doc.mak
# The top-level SGML file. Change it if you want.
DOC_MAIN_SGML_FILE=$(DOC_MODULE)-docs.sgml
# The directory containing the source code.
# gtk-doc will search all .c & .h files beneath here for inline comments
# documenting functions and macros.
DOC_SOURCE_DIR=$(top_srcdir)/gst-libs/gst
# Extra options to supply to gtkdoc-scan.
SCAN_OPTIONS=--deprecated-guards="GST_DISABLE_DEPRECATED" \
--ignore-decorators="GST_API|GST_BASE_API|GST_CHECK_API|GST_CONTROLLER_API|GST_NET_API|GST_ALLOCATORS_API|GST_APP_API|GST_AUDIO_API|GST_FFT_API|GST_GL_API|GST_PBUTILS_API|GST_RIFF_API|GST_RTP_API|GST_RTSP_API|GST_SDP_API|GST_TAG_API|GST_VIDEO_API|GST_ADAPTIVE_DEMUX_API|GST_AUDIO_BAD_API|GST_BASE_CAMERA_BIN_SRC_API|GST_CODEC_PARSERS_API|GST_INSERT_BIN_API|GST_ISOFF_API|GST_PHOTOGRAPHY_API|GST_MPEGTS_API|GST_OPENCV_API|GST_PLAYER_API|GST_URI_DOWNLOADER_API|GST_VIDEO_BAD_API|GST_WAYLAND_API|GST_WEBRTC_API"
# Extra options to supply to gtkdoc-mkdb.
MKDB_OPTIONS=--sgml-mode --output-format=xml
# Extra options to supply to gtkdoc-fixref.
FIXXREF_OPTIONS=--extra-dir=$(GLIB_PREFIX)/share/gtk-doc/html \
--extra-dir=$(GST_PREFIX)/share/gtk-doc/html
# Used for dependencies.
HFILE_GLOB=$(top_srcdir)/gst-libs/gst/*/*.h
CFILE_GLOB=$(top_srcdir)/gst-libs/gst/*/*.c
# Header files to ignore when scanning.
IGNORE_HFILES = \
$(top_srcdir)/gst-libs/gst/mpegts/gstmpegts-private.h \
$(top_srcdir)/gst-libs/gst/player/gstplayer-signal-dispatcher-private.h \
$(top_srcdir)/gst-libs/gst/player/gstplayer-video-renderer-private.h \
$(top_srcdir)/gst-libs/gst/player/gstplayer-media-info-private.h
# Images to copy into HTML directory.
HTML_IMAGES =
# Extra SGML files that are included by $(DOC_MAIN_SGML_FILE).
content_files = compiling.sgml
# Other files to distribute.
extra_files =
# CFLAGS and LDFLAGS for compiling scan program. Only needed if your app/lib
# contains GtkObjects/GObjects and you want to document signals and properties.
GTKDOC_CFLAGS = -DGST_USE_UNSTABLE_API $(GST_PLUGINS_BAD_CFLAGS) $(GST_PLUGINS_BASE_CFLAGS) $(GST_BASE_CFLAGS)
GTKDOC_LIBS = \
$(top_builddir)/gst-libs/gst/audio/libgstbadaudio-@GST_API_VERSION@.la \
$(top_builddir)/gst-libs/gst/codecparsers/libgstcodecparsers-@GST_API_VERSION@.la \
$(top_builddir)/gst-libs/gst/insertbin/libgstinsertbin-@GST_API_VERSION@.la \
$(top_builddir)/gst-libs/gst/mpegts/libgstmpegts-@GST_API_VERSION@.la \
$(top_builddir)/gst-libs/gst/player/libgstplayer-@GST_API_VERSION@.la \
$(top_builddir)/gst-libs/gst/webrtc/libgstwebrtc-@GST_API_VERSION@.la \
$(GST_BASE_LIBS)
# If you need to override some of the declarations, place them in this file
# and uncomment this line.
DOC_OVERRIDES = $(DOC_MODULE)-overrides.txt
include $(top_srcdir)/common/gtk-doc.mak
# Adaptive Demux library
\ No newline at end of file
# Base classes from -bad
> NOTE: This library API is considered *unstable*
# Bitstream parsing Library
This library should be linked to by getting cflags and libs from
gstreamer-plugins-bad-{{ gst_api_version.md }}.pc and adding
-lgstcodeparsers-{{ gst_api_version.md }} to the library flags.
> NOTE: This library API is considered *unstable*
<?xml version="1.0"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
<!ENTITY % version-entities SYSTEM "version.entities">
%version-entities;
]>
<refentry id="compiling" revision="17 Jan 2002">
<refmeta>
<refentrytitle>Compiling</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GStreamer-Bad Library</refmiscinfo>
</refmeta>
<refnamediv>
<refname>Compiling against the bad plugins libraries</refname>
<refpurpose>
How to compile against the bad plugins libraries
</refpurpose>
</refnamediv>
<refsect1>
<title>Compiling against the bad plugins libraries</title>
<para>
To compile against these libraries, you need to tell the compiler where to
find the header files and libraries. This is done with the
<application>pkg-config</application> utility.
</para>
<para>
The following interactive shell session demonstrates how
<application>pkg-config</application> is used:
<programlisting>
$ pkg-config --cflags gstreamer-plugins-bad-&GST_API_VERSION;
-D_LARGEFILE_SOURCE -D_FILE_OFFSET_BITS=64 -pthread -I/usr/include/gstreamer-&GST_API_VERSION; -I/usr/include/glib-2.0 -I/usr/lib/glib-2.0/include -I/usr/include/libxml2
$ pkg-config --libs gstreamer-plugins-bad-&GST_API_VERSION;
-Wl,--export-dynamic -pthread -lgstreamer-&GST_API_VERSION; -lgobject-2.0 -lgmodule-2.0 -ldl -lgthread-2.0 -lxml2 -lpthread -lz -lm -lglib-2.0
</programlisting>
</para>
<para>
Note that, because of the number of libraries provided in this package,
the pkg-config information <emphasis>does not add -l flags</emphasis> itself
to choose the libraries to link to. You must add these yourself to select
which of the libraries you want to use.
</para>
</refsect1>
</refentry>
<?xml version="1.0"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
<!ENTITY % version-entities SYSTEM "version.entities">
%version-entities;
]>
<book id="index" xmlns:xi="http://www.w3.org/2003/XInclude">
<bookinfo>
<title>GStreamer Bad Plugins &GST_API_VERSION; Library Reference Manual</title>
<releaseinfo>
for GStreamer Bad Library &GST_API_VERSION; (&GST_VERSION;)
<ulink role="online-location" url="http://gstreamer.freedesktop.org/data/doc/gstreamer/head/gst-plugins-bad-libs/html/">http://gstreamer.freedesktop.org/data/doc/gstreamer/head/gst-plugins-bad-libs/html/</ulink>.
</releaseinfo>
</bookinfo>
<part id="gstreamer-plugins-bad">
<title>GStreamer Bad Plugins Libraries</title>
<para>
This manual describes the libraries provided by the GStreamer Bad Plugins
package.
</para>
<xi:include href="compiling.sgml" />
<chapter id="codecparsers">
<title>Bitstream parsing Library</title>
<para>
This library should be linked to by getting cflags and libs from
<filename>gstreamer-plugins-bad-&GST_API_VERSION;.pc</filename> and adding
<filename>-lgstcodeparsers-&GST_API_VERSION;</filename> to the library flags.
</para>
<xi:include href="xml/gsth264parser.xml" />
<xi:include href="xml/gstjpegparser.xml" />
<xi:include href="xml/gstmpegvideoparser.xml" />
<xi:include href="xml/gstmpeg4parser.xml" />
<xi:include href="xml/gstvc1parser.xml" />
<xi:include href="xml/gstmpegvideometa.xml" />
</chapter>
<chapter id="mpegts">
<title>Mpeg TS helper library</title>
<para>
This library should be linked to by getting cflags and libs from
<filename>gstreamer-plugins-bad-&GST_API_VERSION;.pc</filename> and adding
<filename>-lgstmpegts-&GST_API_VERSION;</filename> to the library flags.
</para>
<xi:include href="xml/gstmpegts.xml" />
<xi:include href="xml/gstmpegtssection.xml" />
<xi:include href="xml/gstmpegtsdescriptor.xml" />
<xi:include href="xml/gst-atsc-section.xml" />
<xi:include href="xml/gst-dvb-section.xml" />
<xi:include href="xml/gst-atsc-descriptor.xml" />
<xi:include href="xml/gst-dvb-descriptor.xml" />
<xi:include href="xml/gst-isdb-descriptor.xml" />
</chapter>
<chapter id="tools">
<title>Useful elements</title>
<xi:include href="xml/gstinsertbin.xml" />
</chapter>
<chapter id="player">
<title>Player Library</title>
<xi:include href="xml/gstplayer.xml"/>
<xi:include href="xml/gstplayer-mediainfo.xml"/>
<xi:include href="xml/gstplayer-gmaincontextsignaldispatcher.xml"/>
<xi:include href="xml/gstplayer-videooverlayvideorenderer.xml"/>
<xi:include href="xml/gstplayer-visualization.xml"/>
</chapter>
<chapter id="webrtc">
<title>WebRTC Library</title>
<xi:include href="xml/gstwebrtc-dtlstransport.xml"/>
<xi:include href="xml/gstwebrtc-icetransport.xml"/>
<xi:include href="xml/gstwebrtc-receiver.xml"/>
<xi:include href="xml/gstwebrtc-sender.xml"/>
<xi:include href="xml/gstwebrtc-sessiondescription.xml"/>
<xi:include href="xml/gstwebrtc-transceiver.xml"/>
</chapter>
<chapter>
<title>Interfaces</title>
<xi:include href="xml/gstphotography.xml" />
</chapter>
</part>
<part id="gstreamer-libs-hierarchy">
<title>Object Hierarchy</title>
<xi:include href="xml/tree_index.sgml" />
</part>
<index id="api-index-full">
<title>Index</title>
<xi:include href="xml/api-index-full.xml"><xi:fallback /></xi:include>
</index>
<index id="api-index-deprecated" role="deprecated">
<title>Index of deprecated API</title>
<xi:include href="xml/api-index-deprecated.xml"><xi:fallback /></xi:include>
</index>
<xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>
</book>
#include <gst/gst.h>
#include <gst/codecparsers/gsth264parser.h>
#include <gst/codecparsers/gstmpegvideoparser.h>
#include <gst/insertbin/gstinsertbin.h>
#include <gst/mpegts/mpegts.h>
#include <gst/player/player.h>
#include <gst/webrtc/webrtc.h>
gst_mpegts_section_get_type
gst_mpegts_section_type_get_type
gst_mpegts_section_table_id_get_type
gst_mpegts_descriptor_get_type
gst_mpegts_cable_outer_fec_scheme_get_type
gst_mpegts_modulation_type_get_type
gst_mpegts_satellite_polarization_type_get_type
gst_mpegts_satellite_rolloff_get_type
gst_mpegts_dvb_code_rate_get_type
gst_mpegts_descriptor_type_get_type
gst_mpegts_iso639_audio_type_get_type
gst_mpegts_running_status_get_type
gst_mpegts_dvb_service_type_get_type
gst_mpegts_stream_type_get_type
gst_mpegts_section_atsc_table_id_get_type
gst_mpegts_atsc_mgt_table_type_get_type
gst_mpegts_atsc_vct_get_type
gst_mpegts_atsc_vct_source_get_type
gst_mpegts_atsc_mgt_get_type
gst_mpegts_atsc_mgt_table_get_type
gst_mpegts_atsc_string_segment_get_type
gst_mpegts_atsc_mult_string_get_type
gst_mpegts_atsc_eit_event_get_type
gst_mpegts_atsc_eit_get_type
gst_mpegts_atsc_ett_get_type
gst_mpegts_atsc_stt_get_type
gst_insert_bin_get_type
gst_player_audio_info_get_type
gst_player_color_balance_type_get_type
gst_player_error_get_type
gst_player_g_main_context_signal_dispatcher_get_type
gst_player_get_type
gst_player_media_info_get_type
gst_player_signal_dispatcher_get_type
gst_player_state_get_type
gst_player_stream_info_get_type
gst_player_subtitle_info_get_type
gst_player_video_info_get_type
gst_player_video_overlay_video_renderer_get_type
gst_player_video_renderer_get_type
gst_player_visualization_get_type
gst_webrtc_dtls_setup_get_type
gst_webrtc_dtls_transport_get_type
gst_webrtc_dtls_transport_state_get_type
gst_webrtc_ice_component_get_type
gst_webrtc_ice_connection_state_get_type
gst_webrtc_ice_gathering_state_get_type
gst_webrtc_ice_role_get_type
gst_webrtc_sdp_type_get_type
gst_webrtc_ice_transport_get_type
gst_webrtc_peer_connection_state_get_type
gst_webrtc_rtp_receiver_get_type
gst_webrtc_rtp_sender_get_type
gst_webrtc_session_description_get_type
gst_webrtc_signaling_state_get_type
gst_webrtc_rtp_transceiver_direction_get_type
gst_webrtc_rtp_transceiver_get_type
gst_webrtc_stats_type_get_type
---
short-description: A library that contains a bin to insertally link filter-like elements.
...
# GstInsertBin
> NOTE: This library API is considered *unstable*
# Mpeg TS helper library
This library should be linked to by getting cflags and libs from
gstreamer-plugins-bad-{{ gst_api_version.md }}.pc and adding
-lgstmpegts-{{ gst_api_version.md }} to the library flags.
> NOTE: This library API is considered *unstable*
# Player Library
> NOTE: This library API is considered *unstable*
# Useful elements
> NOTE: This library API is considered *unstable*
# Video helpers and baseclasses
> NOTE: This library API is considered *unstable*
# WebRTC Library
This library should be linked to by getting cflags and libs from
gstreamer-webrtc-{{ gst_api_version.md }}
> NOTE: This library API is considered *unstable*
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', 'c-extension', 'gst-extension']
if gst_dep.type_name() == 'internal'
gst_proj = subproject('gstreamer')
plugins_cache_generator = gst_proj.get_variable('plugins_cache_generator')
else
required_hotdoc_extensions += ['gst-extension']
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('bad-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 gi-extension missing')
endif
message('@0@ extensions not found, not building documentation requiring it'.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)
configure_file(input : 'gst_api_version.in',
output : 'gst_api_version.md',
configuration : docconf)
root_rel = '..'
excludes = []
foreach f: [
'gst/frei0r/frei0r.h',
'gst/mxf/mxful.c',
'gst-libs/gst/mpegts/gstmpegts-private.h',
'gst-libs/gst/player/*-private.h',
'gst-libs/gst/codecparsers/nalutils.h',
'ext/closedcaption/bcd.h',
'ext/closedcaption/bit_slicer.[ch]',
'ext/closedcaption/decoder.[ch]',
'ext/closedcaption/macros.h',
'ext/closedcaption/misc.h',
'ext/closedcaption/raw_decoder.[ch]',
'ext/closedcaption/sampling_par.[ch]',
'ext/closedcaption/sliced.[ch]',
'ext/*/*.h',
'sys/*/*.h',
'gst/*/*.h',
'gst-libs/gst/*/*-prelude.h'
]
excludes += [join_paths(meson.current_source_dir(), root_rel, f)]
endforeach
libs = []
if build_gir
libs = [
{'name': 'mpegts', 'gir': mpegts_gir, 'lib': gstmpegts_dep},
{'name': 'player', 'gir': player_gir, 'lib': gstplayer_dep},
{'name': 'insertbin', 'gir': insertbin_gir, 'lib': gstinsertbin_dep},
{'name': 'codecparsers', 'lib': gstcodecparsers_dep},
{'name': 'adaptivedemux', 'lib': gstadaptivedemux_dep},
{'name': 'webrtc', 'gir': webrtc_gir, 'lib': gstwebrtc_dep},
]
endif
has_gi_extension = hotdoc.has_extensions('gi-extension')
has_c_extension = hotdoc.has_extensions('c-extension')