Commit 93c2e7d6 authored by George Kiagiadakis's avatar George Kiagiadakis
Browse files

meson: refactor docs + gi build system

* Use custom_target() instead of configured shell scripts
* Do not copy all the .rst files in the build directory
* Setup dependencies between targets
* Tidy up dependencies lookup
* Remove unused files
* Upgrade Doxyfile to the latest version and cleanup used options
parent 2e5b13f9
This diff is collapsed.
# you need to add here any files you add to the api directory as well
files = [
sphinx_files += files(
'library_root.rst',
'client_api.rst',
'components_api.rst',
......@@ -27,8 +27,4 @@ files = [
'spa_type_api.rst',
'spa_pod_api.rst',
'wp_api.rst'
]
foreach file : files
configure_file(input: file, output: file, copy: true)
endforeach
)
......@@ -10,19 +10,19 @@
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#
import os
import sys
sys.path.insert(0, os.path.abspath('.'))
#import os
#import sys
#sys.path.insert(0, os.path.abspath('.'))
# -- Project information -----------------------------------------------------
project = 'WirePlumber'
copyright = '2020, Collabora'
copyright = '2021, Collabora'
author = 'Collabora'
# The full version, including alpha/beta/rc tags
release = '2020'
release = '@VERSION@'
# -- General configuration ---------------------------------------------------
......@@ -32,9 +32,13 @@ release = '2020'
# ones.
extensions = [
'breathe',
'sphinx_rtd_theme',
]
breathe_projects = { "WirePlumber": "@BUILD_ROOT@/xml", "WirePlumber_Lua" : "@BUILD_ROOT@/xml", }
breathe_projects = {
"WirePlumber": "@OUTDIR@/wp/xml",
"WirePlumber_Lua" : "@OUTDIR@/lua/xml",
}
breathe_default_members = ('members', 'undoc-members')
breathe_default_project = "WirePlumber"
......@@ -51,28 +55,22 @@ breathe_domain_by_extension = {
# See, https://breathe.readthedocs.io/en/latest/directives.html#config-values for more information
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
#templates_path = ['_templates']
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This pattern also affects html_static_path and html_extra_path.
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
exclude_patterns = ['meson.build']
# -- Options for HTML output -------------------------------------------------
# on_rtd is whether we are on readthedocs.org, this line of code grabbed from docs.readthedocs.org
on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
if not on_rtd: # only import and set the theme if we're building docs locally
import sphinx_rtd_theme
html_theme = 'sphinx_rtd_theme'
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
html_theme = 'sphinx_rtd_theme'
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']
#html_static_path = ['_static']
# Tell sphinx what the primary language being documented is.
primary_domain = 'cpp'
primary_domain = 'c'
sphinx_p = find_program('sphinx-build', required: get_option('doc'))
if not sphinx_p.found()
message('Sphinx not found, not building the documentation')
subdir_done()
endif
if not doxygen_p.found()
message('Doxygen not found, not building the documentation')
subdir_done()
endif
breathe_p = find_program('breathe-apidoc', required: get_option('doc'))
if not breathe_p.found()
message('Breathe not found, not building the documentation')
subdir_done()
endif
# Find dependencies
pymod = import('python')
lxml_p = pymod.find_installation(
modules: [
'lxml',
],
python_doc = pymod.find_installation(
'python3',
modules: ['sphinx', 'sphinx_rtd_theme', 'breathe'],
required: get_option('doc')
)
if not lxml_p.found()
message('lxml not found, not building gtk documentation from Doxygen')
subdir_done()
endif
sphinx_c = run_command(sphinx_p, '--version')
breathe_c = run_command(breathe_p, '--version')
doxygen_c = run_command(doxygen_p, '--version')
sphinx_v = sphinx_c.stdout().split(' ')[1].strip()
breathe_v = breathe_c.stdout().split(' ')[2].strip()
doxygen_v = doxygen_c.stdout().strip()
python_gir = pymod.find_installation(
'python3',
modules: ['lxml'],
required: get_option('introspection')
)
if sphinx_v.version_compare('< 2.1.0')
error('Use at least sphinx version 2.1.0, found ' + sphinx_v)
if get_option('doc').enabled() or get_option('introspection').enabled()
doxygen_p = find_program('doxygen', version: '>= 1.9.0', required: true)
elif get_option('doc').auto() or get_option('introspection').auto()
doxygen_p = find_program('doxygen', version: '>= 1.9.0', required: false)
else
doxygen_p = disabler()
endif
if breathe_v.version_compare('< 4.11')
error('Use at least breathe version 4.11, found ' + breathe_v)
sphinx_p = find_program('sphinx-build',
version: '>= 2.1.0', required: get_option('doc'))
gir_p = find_program('g-ir-scanner', required: get_option('introspection'))
build_doc = python_doc.found() and doxygen_p.found() and sphinx_p.found()
build_gir = python_gir.found() and doxygen_p.found() and gir_p.found()
# Run doxygen (common for docs and g-i)
if build_doc or build_gir
doxy_wp_conf_data = configuration_data()
doxy_wp_conf_data.set('OUTPUT_DIR', meson.current_build_dir() / 'wp')
doxy_wp_conf_data.set('INPUT', meson.source_root() / 'lib' / 'wp')
doxyfile_wp = configure_file(
input: 'Doxyfile.in',
output: 'Doxyfile-wp',
configuration: doxy_wp_conf_data
)
doxyxml_wp_depfiles = [wp_lib_sources, wp_lib_headers]
doxyxml_wp = custom_target('doxyxml_wp',
command: [doxygen_p, doxyfile_wp],
depend_files: doxyxml_wp_depfiles,
output: 'wp',
build_by_default: true,
)
endif
if doxygen_v.version_compare('< 1.8')
error('Use at least doxygen version 1.8, found ' + doxygen_v)
# Build documentation
if build_doc
doxy_lua_input = [
meson.source_root() / 'modules' / 'module-lua-scripting' / 'api.c',
meson.source_root() / 'modules' / 'module-lua-scripting' / 'pod.c',
]
doxy_lua_conf_data = configuration_data()
doxy_lua_conf_data.set('OUTPUT_DIR', meson.current_build_dir() / 'lua')
doxy_lua_conf_data.set('INPUT', ' \\\n '.join(doxy_lua_input))
doxyfile_lua = configure_file(
input: 'Doxyfile.in',
output: 'Doxyfile-lua',
configuration: doxy_lua_conf_data
)
doxyxml_lua_depfiles = doxy_lua_input
doxyxml_lua = custom_target('doxyxml_lua',
command: [doxygen_p, doxyfile_lua],
depend_files: doxyxml_lua_depfiles,
output: 'lua',
build_by_default: true,
)
sphinx_files = files('index.rst')
subdir('api')
subdir('toc')
sphinx_conf_data = configuration_data()
sphinx_conf_data.set('OUTDIR', meson.current_build_dir())
sphinx_conf_data.set('VERSION', meson.project_version())
sphinx_conf = configure_file(
input: 'conf.py.in',
output: 'conf.py',
configuration: sphinx_conf_data
)
custom_target('doc',
command: [sphinx_p,
'-q', # quiet
'-E', # rebuild from scratch
'-j', 'auto', # parallel build
'-d', '@PRIVATE_DIR@', # doctrees dir
'-c', '@OUTDIR@', # conf.py dir
'@CURRENT_SOURCE_DIR@', # source dir
'@OUTPUT@', # output dir
],
depend_files: [
sphinx_conf, sphinx_files,
doxyxml_wp_depfiles, doxyxml_lua_depfiles,
],
depends: [doxyxml_wp, doxyxml_lua],
output: 'html',
install: true,
install_dir: get_option('datadir') / 'doc' / 'wireplumber',
build_by_default: true,
)
endif
if not build_gir
if get_option('doc').enabled()
error('Documentation enabled but introspection not built.')
endif
# Build GObject introspection
if build_gir
wp_gtkdoc_h = custom_target('wp_gtkdoc_h',
command: [python_gir,
'@CURRENT_SOURCE_DIR@/gen-api-gtkdoc.py',
'-o', '@OUTPUT@',
'@OUTDIR@/wp/xml',
],
depends: [doxyxml_wp],
depend_files: doxyxml_wp_depfiles,
output: 'wp-gtkdoc.h',
build_by_default: true,
)
gnome.generate_gir(wp_lib,
namespace: 'Wp',
nsversion: wireplumber_api_version,
sources: [wpenums_c, wpenums_h, wp_gtkdoc_h],
includes: ['GLib-2.0', 'GObject-2.0', 'Gio-2.0'],
install: true,
)
endif
doxygen_database = meson.current_build_dir() + '/doxygen_doc'
# modify the sphinx configuration and the breathe doxygen XML database
# to point where its being generated by doxygen
sphinx_conf_data = configuration_data()
sphinx_conf_data.set('BUILD_ROOT', doxygen_database)
sphinx_conf_data.set('VERSION', meson.project_version())
sphinx_conf = configure_file(
input: 'conf.py.in',
output: 'conf.py',
configuration: sphinx_conf_data
)
# build gir
doxy_conf_data = configuration_data()
doxy_conf_data.set('SRC_ROOT', meson.source_root())
doxy_conf_data.set('OUTPUT_DIR', doxygen_database)
doxygen_conf_wireplumber = configure_file(
input: 'doxyfile.in',
output: 'doxyfile',
configuration: doxy_conf_data
)
dir_prefix = get_option('prefix')
dir_data = join_paths(dir_prefix, get_option('datadir'))
script_data = configuration_data()
script_data.set('SRCDIR', meson.current_build_dir())
script_data.set('OUTDIR', meson.current_build_dir() + '/docs')
# Set a different directory for doctrees to avoid installing them
script_data.set('DOCTREES_DIR', meson.current_build_dir() + '/doctrees')
script_data.set('SPHINX_CMD', sphinx_p.path())
script_doxy_sphinx = configure_file(
input: 'run_doxygen_sphinx.sh.in',
output: 'run_doxygen_sphinx.sh',
configuration: script_data
)
# copy everything to build_dir, if you plan on adding other files in the top
# rootdir of sourcedir, please add them here as well, otherwise use 'toc/'s
# meson.build file
sphinx_files = ['index.rst']
foreach file : sphinx_files
configure_file(input: file, output: file, copy: true)
endforeach
# and those in toc and api
subdir('toc')
subdir('api')
sphinx_doc = custom_target(
'breathe',
command: script_doxy_sphinx,
output: 'docs',
build_by_default: true,
)
# we need this because we will have a stale 'docs' directory
# and this forces it to be rebuilt
docs = run_target(
'docs',
command: script_doxy_sphinx,
)
install_subdir(
sphinx_doc.full_path(),
install_dir: join_paths(dir_data, 'doc', 'wireplumber', 'html'),
exclude_files: '.buildinfo',
strip_directory: true,
)
bs4 # BeautifulSoup!
lxml # We need the lxml backend for BeautifulSoup.
sphinx>=1.6.1 # 1.6 introduces logging API.
breathe # The directives used for documentation come from the excellent Breathe.
six # Primarily for Unicode string types
#!/bin/sh
@SPHINX_CMD@ -E -Q -j auto -d @DOCTREES_DIR@ @SRCDIR@ @OUTDIR@
#!/bin/sh
@DOXYGEN_CMD@ @DOXYGEN_CONF@ && @PYTHON@ @GIR_PY_SCRIPT@ @XML_DIR@ -d @XML_DIR@ -o @OUTDIR@/wp-gtkdoc.h
\ No newline at end of file
# you need to add here any files you add to the toc directory as well
files = [
sphinx_files += files(
'lua_core_api.rst',
'lua_client_api.rst',
'lua_endpoint_api.rst',
......@@ -15,8 +15,4 @@ files = [
'lua_session_item_api.rst',
'lua_source_api.rst',
'lua_spa_device_api.rst',
]
foreach file : files
configure_file(input: file, output: file, copy: true)
endforeach
)
# you need to add here any files you add to the toc directory as well
files = [
sphinx_files += files(
'installing-wireplumber.rst',
'running-wireplumber-daemon.rst',
'daemon-configuration.rst',
......@@ -8,10 +8,6 @@ files = [
'community.rst',
'testing.rst',
'lua_api.rst'
]
foreach file : files
configure_file(input: file, output: file, copy: true)
endforeach
)
subdir('lua_api')
wp_lib_sources = files(
'private/pipewire-object-mixin.c',
'client.c',
'component-loader.c',
'core.c',
......@@ -30,6 +29,10 @@ wp_lib_sources = files(
'wp.c',
)
wp_lib_priv_sources = files(
'private/pipewire-object-mixin.c',
)
wp_lib_headers = files(
'client.h',
'component-loader.h',
......@@ -89,7 +92,7 @@ wpversion = configure_file(
wp_gen_sources += [wpversion]
wp_lib = library('wireplumber-' + wireplumber_api_version,
wp_lib_sources, wpenums_c, wpenums_h, wpversion,
wp_lib_sources, wp_lib_priv_sources, wpenums_c, wpenums_h, wpversion,
c_args : [
'-D_GNU_SOURCE',
'-DG_LOG_USE_STRUCTURED',
......@@ -105,44 +108,6 @@ wp_lib = library('wireplumber-' + wireplumber_api_version,
version: meson.project_version(),
)
if build_gir
wp_gtkdoc_conf = configure_file(
input: '../../docs/gen-api-gtkdoc.py.in',
output: 'gen-api-gtkdoc.py',
copy: true
)
script_data = configuration_data()
script_data.set('PYTHON', 'python3')
script_data.set('OUTDIR', meson.current_build_dir())
script_data.set('GIR_PY_SCRIPT', meson.current_build_dir() + '/gen-api-gtkdoc.py')
script_data.set('XML_DIR', meson.build_root() + '/docs/doxygen_doc/xml')
script_data.set('DOXYGEN_CONF', meson.build_root() + '/docs/doxyfile')
script_data.set('DOXYGEN_CMD', doxygen_p.path())
script_gen_api = configure_file(
input: '../../docs/run_gen_api.sh.in',
output: 'run_gen_api.sh',
configuration: script_data
)
wp_gtkdoc_h = custom_target(
'gir',
command: script_gen_api,
output: 'wp-gtkdoc.h',
build_by_default: true,
)
wp_gir = gnome.generate_gir(wp_lib,
namespace: 'Wp',
nsversion: wireplumber_api_version,
sources: [wpenums_c, wpenums_h, wp_gtkdoc_h],
includes: ['GLib-2.0', 'GObject-2.0', 'Gio-2.0'],
install: true,
)
wp_gen_sources += wp_gir
endif
wp_dep = declare_dependency(
link_with: wp_lib,
sources: wp_gen_sources,
......
......@@ -68,8 +68,6 @@ endif
gnome = import('gnome')
pkgconfig = import('pkgconfig')
gir = find_program('g-ir-scanner', required : get_option('introspection'))
build_gir = gir.found()
wp_lib_include_dir = include_directories('lib')
......@@ -93,8 +91,6 @@ common_flags = [
]
add_project_arguments(cc.get_supported_arguments(common_flags), language: 'c')
doxygen_p = find_program('doxygen', required: get_option('doc'))
subdir('lib')
subdir('docs')
subdir('modules')
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment