libvirt/docs/meson.build
Peter Krempa 07467e2719 docs: Prohibit 'external' links within the webpage
Enforce that relative links are used within the page, so that local
installations don't require internet conection and/or don't redirect to
the web needlessly.

This is done by looking for any local link (barring exceptions) when
checking links with 'check-html-references.py'.

Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
2024-10-09 16:00:44 +02:00

373 lines
8.7 KiB
Meson

docs_html_dir = docdir / 'html'
# xsltproc requires that the -o path ends with '/'
# Not using '/' operator due to bug in meson 0.60.0
# https://github.com/mesonbuild/meson/issues/9450
docs_builddir = join_paths(meson.current_build_dir(), '')
docs_assets = [
'android-chrome-192x192.png',
'android-chrome-256x256.png',
'apple-touch-icon.png',
'browserconfig.xml',
'favicon.ico',
'favicon-16x16.png',
'favicon-32x32.png',
'manifest.json',
'mstile-150x150.png',
]
docs_rst_files = [
'aclpolkit',
'advanced-tests',
'api',
'api_extension',
'apps',
'auditlog',
'auth',
'best-practices',
'bindings',
'bugs',
'cgroups',
'ci',
'ci-dashboard',
'ci-runners',
'clangd',
'coding-style',
'committer-guidelines',
'compiling',
'contact',
'contribute',
'csharp',
'daemons',
'dbus',
'docs',
'downloads',
'drivers',
'drvbhyve',
'drvch',
'drvesx',
'drvhyperv',
'drvlxc',
'drvnodedev',
'drvopenvz',
'drvqemu',
'drvsecret',
'drvtest',
'drvvbox',
'drvvirtuozzo',
'drvvmware',
'drvxen',
'errors',
'firewall',
'format',
'formatbackup',
'formatcaps',
'formatcheckpoint',
'formatdomain',
'formatdomaincaps',
'formatnetwork',
'formatnetworkport',
'formatnode',
'formatnwfilter',
'formatsecret',
'formatsnapshot',
'formatstorage',
'formatstoragecaps',
'formatstorageencryption',
'glib-adoption',
'goals',
'golang',
'governance',
'hacking',
'hooks',
'index',
'issue-handling',
'libvirt-go',
'libvirt-go-xml',
'logging',
'macos',
'migration',
'newreposetup',
'nss',
'pci-addresses',
'pci-hotplug',
'platforms',
'programming-languages',
'python',
'remote',
'securityprocess',
'ssh-proxy',
'storage',
'strategy',
'styleguide',
'submitting-patches',
'support',
'testapi',
'testing',
'testtck',
'uri',
'windows',
]
# list of web targets to build for docs/web rule
install_web_deps = []
install_web_files = []
install_data(docs_assets, install_dir: docs_html_dir)
aclperms_gen = custom_target(
'aclperms.htmlinc',
input: access_perm_h,
output: 'aclperms.htmlinc',
command: [
genaclperms_prog, '@INPUT@',
],
capture: true,
)
docs_timestamp = run_command(
python3_prog, meson_timestamp_prog.full_path(), env: runutf8, check: true,
).stdout().strip()
site_xsl = files('site.xsl')
page_xsl = files('page.xsl')
newapi_xsl = files('newapi.xsl')
docs_api_generated = custom_target(
'generate-api',
output: [
'libvirt-api.xml',
'libvirt-lxc-api.xml',
'libvirt-qemu-api.xml',
'libvirt-admin-api.xml',
],
command: [
apibuild_prog,
meson.current_source_dir(),
meson.current_build_dir(),
],
install: true,
install_dir: pkgdatadir / 'api',
depend_files: [
libvirt_common_h_in,
libvirt_include,
driver_sources,
libvirt_qemu_sources,
libvirt_lxc_sources,
admin_sources,
util_public_sources,
meson.project_source_root() / 'src' / 'remote' / 'remote_protocol.x',
meson.project_source_root() / 'src' / 'remote' / 'qemu_protocol.x',
meson.project_source_root() / 'src' / 'remote' / 'lxc_protocol.x',
],
)
docs_api_xml = docs_api_generated[0]
docs_lxc_api_xml = docs_api_generated[1]
docs_qemu_api_xml = docs_api_generated[2]
docs_admin_api_xml = docs_api_generated[3]
docs_programs_groups = [
{ 'name': 'rst2html5', 'prog': [ 'rst2html5', 'rst2html5.py', 'rst2html5-3' ] },
{ 'name': 'rst2man', 'prog': [ 'rst2man', 'rst2man.py', 'rst2man-3' ] },
]
foreach item : docs_programs_groups
prog = find_program(item.get('prog'), dirs: libvirt_sbin_path)
varname = item.get('name').underscorify()
conf.set_quoted(varname.to_upper(), prog.full_path())
set_variable('@0@_prog'.format(varname), prog)
endforeach
# There are two versions of rst2html5 in the wild: one is the version
# coming from the docutils package, and the other is the one coming
# from the rst2html5 package. These versions are subtly different,
# and the libvirt documentation can only be successfully generated
# using the docutils version. Every now and then, users will report
# build failures that can be traced back to having the wrong version
# installed.
#
# The only reliable way to tell the two binaries apart seems to be
# looking look at their version information: the docutils version
# will report
#
# rst2html5 (Docutils ..., Python ..., on ...)
#
# whereas the rst2html5 version will report
#
# rst2html5 ... (Docutils ..., Python ..., on ...)
#
# with the additional bit of information being the version number for
# the rst2html5 package itself.
#
# Use this knowledge to detect the version that we know doesn't work
# for building libvirt and reject it
rst2html5_version = run_command(rst2html5_prog, '--version', check: true)
rst2html5_version = rst2html5_version.stdout().split(' ')
if rst2html5_version[1] != '(Docutils'
error('Please uninstall the rst2html5 package and install the docutils package')
endif
docs_rst2html5_gen = generator(
rst2html5_prog,
output: '@BASENAME@.html.in',
arguments: [ '--exit-status=1', '--stylesheet=', '--strict', '@INPUT@' ],
capture: true,
)
# html_xslt_gen config
html_xslt_gen_install_dir = docs_html_dir
html_xslt_gen = []
# html_xslt_gen:
# each entry is a dictionary with following items:
# name - base file name (required), output file will become 'name.html'
# file - input file (optional, 'name.html.in' assumed if missing)
# source - source filename relative to repository root (optional, if there is no source)
# depends - explicit dependency on other input (optional)
foreach name : docs_rst_files
rst_file = '@0@.rst'.format(name)
html_xslt_gen += {
'name': name,
'file': docs_rst2html5_gen.process(rst_file),
'source': 'docs' / rst_file,
}
endforeach
html_xslt_gen += {
'name': 'acl',
'file': docs_rst2html5_gen.process('acl.rst'),
'source': 'docs' / 'acl.rst',
'depends': aclperms_gen,
}
html_xslt_gen += {
'name': '404',
'file': docs_rst2html5_gen.process('404.rst'),
'source': 'docs' / '404.rst',
'href_base': '/',
}
hvsupport_html_in = custom_target(
'hvsupport.html.in',
output: 'hvsupport.html.in',
command: [
hvsupport_prog,
meson.project_source_root(),
meson.project_build_root(),
],
capture: true,
depend_files: [
public_sym_file,
libvirt_qemu_syms,
libvirt_lxc_syms,
driver_header,
],
depends: [
docs_api_generated,
],
)
html_xslt_gen += {
'name': 'hvsupport',
'file': hvsupport_html_in,
}
news_html_in = docs_rst2html5_gen.process(meson.project_source_root() / 'NEWS.rst')
html_xslt_gen += {
'name': 'news',
'file': news_html_in,
'source': 'NEWS.rst',
}
# The following code between the markers must be kept identical with the other
# copies of the code in various subdirs, since meson doesn't support any kind
# of functions.
# --- begin of XSLT processing ---
foreach data : html_xslt_gen
html_filename = data['name'] + '.html'
html_file = custom_target(
html_filename,
input: data.get('file', data['name'] + '.html.in'),
output: html_filename,
command: [
xsltproc_prog,
'--stringparam', 'pagesrc', data.get('source', ''),
'--stringparam', 'builddir', meson.project_build_root(),
'--stringparam', 'timestamp', docs_timestamp,
'--stringparam', 'href_base', data.get('href_base', ''),
'--nonet',
site_xsl,
'@INPUT@',
],
depends: data.get('depends', []),
depend_files: [ page_xsl ],
capture: true,
install: true,
install_dir: html_xslt_gen_install_dir,
)
install_web_deps += html_file
install_web_files += html_file.full_path() + ':' + html_xslt_gen_install_dir
endforeach
html_xslt_gen = []
# --- end of XSLT processing ---
subdir('css')
subdir('fonts')
subdir('go')
subdir('html')
subdir('images')
subdir('js')
subdir('kbase')
subdir('logos')
subdir('manpages')
foreach file : docs_assets
# This hack enables us to view the web pages
# from within the uninstalled build tree
if meson.version().version_compare('>=0.64.0')
fs.copyfile(file)
else
configure_file(input: file, output: file, copy: true)
endif
install_web_files += '@0@:@1@'.format(meson.current_source_dir() / file, docs_html_dir)
endforeach
run_target(
'install-web',
command: [
meson_python_prog, python3_prog.full_path(), meson_install_web_prog.full_path(),
install_web_files,
],
depends: install_web_deps,
)
if tests_enabled[0]
test(
'check-html-references',
python3_prog,
args: [
check_html_references_prog.full_path(),
'--require-https',
'--project-uri', 'https://libvirt.org',
'--project-uri-exceptions', 'docs/manpages/',
'--project-uri-exceptions', 'docs/html/',
'--webroot',
meson.project_build_root() / 'docs'
],
depends: install_web_deps,
env: runutf8,
suite: 'script'
)
endif