summaryrefslogtreecommitdiff
path: root/doc/doxygen
diff options
context:
space:
mode:
Diffstat (limited to 'doc/doxygen')
-rw-r--r--doc/doxygen/.gitignore1
-rwxr-xr-xdoc/doxygen/gen-doxygen.py105
-rw-r--r--doc/doxygen/meson.build105
-rw-r--r--doc/doxygen/xml/Client/meson.build18
-rw-r--r--doc/doxygen/xml/Server/meson.build18
-rw-r--r--doc/doxygen/xml/meson.build22
6 files changed, 268 insertions, 1 deletions
diff --git a/doc/doxygen/.gitignore b/doc/doxygen/.gitignore
index a85e6c0..d68d6fc 100644
--- a/doc/doxygen/.gitignore
+++ b/doc/doxygen/.gitignore
@@ -1,4 +1,3 @@
doxygen_sqlite3.db
html/
wayland.doxygen
-xml/
diff --git a/doc/doxygen/gen-doxygen.py b/doc/doxygen/gen-doxygen.py
new file mode 100755
index 0000000..1bb07e5
--- /dev/null
+++ b/doc/doxygen/gen-doxygen.py
@@ -0,0 +1,105 @@
+#!/usr/bin/env python3
+
+import argparse
+import datetime
+import errno
+import os
+import subprocess
+import sys
+
+# Custom configuration for each documentation format
+doxygen_templates = {
+ 'xml': [
+ 'GENERATE_XML=YES\n',
+ 'XML_OUTPUT={format}/{section}\n',
+ 'INPUT= {files}\n',
+ ],
+ 'html': [
+ 'GENERATE_HTML=YES\n',
+ 'HTML_OUTPUT={format}/{section}\n',
+ 'PROJECT_NAME=\"Wayland {section} API\"\n',
+ 'INPUT= {files}\n',
+ ],
+ 'man': [
+ 'GENERATE_MAN=YES\n',
+ 'MAN_OUTPUT={format}\n',
+ 'MAN_SUBDIR=.\n',
+ 'JAVADOC_AUTOBRIEF=NO\n',
+ 'INPUT= {files}\n',
+ ],
+}
+
+def load_doxygen_file(doxyfile):
+ with open(doxyfile, 'r') as f:
+ res = f.readlines()
+ return res
+
+def get_template(outformat):
+ for (k,v) in doxygen_templates.items():
+ if outformat.startswith(k):
+ return v
+
+def gen_doxygen_file(data, outformat, section, files):
+ for l in get_template(outformat):
+ data.append(l.format(format=outformat, section=section, files=' '.join(files)))
+ return data
+
+parser = argparse.ArgumentParser(description='Generate docs with Doxygen')
+parser.add_argument('doxygen_file',
+ help='The doxygen file to use')
+parser.add_argument('files',
+ help='The list of files to parse',
+ metavar='FILES',
+ nargs='+')
+parser.add_argument('--builddir',
+ help='The build directory',
+ metavar='DIR',
+ default='.')
+parser.add_argument('--section',
+ help='The section to build',
+ metavar='NAME',
+ default='Client')
+parser.add_argument('--output-format',
+ help='The output format: xml, html, man',
+ metavar='FORMAT',
+ default='xml')
+parser.add_argument('--stamp',
+ help='Stamp file to output',
+ metavar='STAMP_FILE',
+ nargs='?',
+ type=argparse.FileType('w'))
+
+args = parser.parse_args()
+
+# Merge the doxyfile with our custom templates
+conf = load_doxygen_file(args.doxygen_file)
+conf = gen_doxygen_file(conf, args.output_format, args.section, args.files)
+
+# Doxygen is not clever enough to create the directories it
+# needs beforehand
+try:
+ os.makedirs(os.path.join(args.builddir, args.output_format))
+except OSError as e:
+ if e.errno != errno.EEXIST:
+ raise e
+
+# Run Doxygen with the generated doxyfile
+cmd = subprocess.Popen(['doxygen', '-'], stdin=subprocess.PIPE)
+cmd.stdin.write(''.join(conf).encode('utf-8'))
+cmd.stdin.close()
+if cmd.wait() != 0:
+ sys.exit(1)
+
+# This is a bit of a hack; Doxygen will generate way more files than we
+# want to install, but there's no way to know how many at configuration
+# time. Since we want to install only the wl_* man pages anyway, we can
+# delete the other files and let Meson install the whole man3 subdirectory
+if args.output_format.startswith('man'):
+ manpath = os.path.join(args.builddir, args.output_format)
+ for filename in os.listdir(manpath):
+ full_path = os.path.join(manpath, filename)
+ if not filename.startswith('wl_'):
+ os.remove(full_path)
+
+if args.stamp:
+ args.stamp.write(str(datetime.datetime.now()))
diff --git a/doc/doxygen/meson.build b/doc/doxygen/meson.build
new file mode 100644
index 0000000..c39b282
--- /dev/null
+++ b/doc/doxygen/meson.build
@@ -0,0 +1,105 @@
+# Here be dragons
+
+dot_gv = {
+ 'wayland-architecture': files('dot/wayland-architecture.gv'),
+ 'x-architecture': files('dot/x-architecture.gv'),
+}
+
+# This is a workaround for Meson's custom_target() directive, which
+# currently does not support outputs pointing to a sub-directory
+# XXX: try turning these into maps, so they can be indexed with picture name
+dot_png = []
+dot_map = []
+
+doxygen_conf = configuration_data()
+doxygen_conf.set('VERSION', meson.project_version())
+doxygen_conf.set('top_builddir', meson.build_root())
+wayland_doxygen = configure_file(
+ input: 'wayland.doxygen.in',
+ output: 'wayland.doxygen',
+ configuration: doxygen_conf,
+)
+
+shared_files = files([
+ '../../src/wayland-util.h',
+])
+
+client_files = files([
+ '../../src/wayland-client.c',
+ '../../src/wayland-client.h',
+ '../../src/wayland-client-core.h',
+])
+
+server_files = files([
+ '../../src/event-loop.c',
+ '../../src/wayland-server.c',
+ '../../src/wayland-server.h',
+ '../../src/wayland-server-core.h',
+ '../../src/wayland-shm.c',
+])
+
+extra_client_files = [
+ 'mainpage.dox',
+ wayland_client_protocol_h,
+]
+
+extra_server_files = [
+ 'mainpage.dox',
+ wayland_server_protocol_h,
+]
+
+gen_doxygen = find_program('gen-doxygen.py')
+
+subdir('xml')
+
+formats = {
+ 'html': {
+ 'Client': shared_files + client_files + extra_client_files,
+ 'Server': shared_files + server_files + extra_server_files,
+ },
+}
+
+foreach f_name, sections: formats
+ foreach s_name, s_files: sections
+ t_name = '@0@-@1@-doc'.format(f_name, s_name)
+
+ # We do not really need an output file, but Meson
+ # will complain if one is not set, so we use a
+ # dummy 'stamp' file
+ custom_target(
+ t_name,
+ command: [
+ gen_doxygen,
+ # XXX pass doxygen path as argument
+ '--builddir=@OUTDIR@',
+ '--section=@0@'.format(s_name),
+ '--output-format=@0@'.format(f_name),
+ '--stamp=doc/doxygen/@0@.stamp'.format(t_name),
+ wayland_doxygen,
+ '@INPUT@',
+ ],
+ input: s_files,
+ output: '@0@.stamp'.format(t_name),
+ depends: [dot_png, dot_map],
+ build_by_default: true,
+ )
+ endforeach
+endforeach
+
+man_files = shared_files + server_files + client_files
+custom_target(
+ 'man-pages-3',
+ command: [
+ gen_doxygen,
+ '--builddir=@OUTDIR@',
+ '--output-format=man3',
+ '--stamp=doc/doxygen/man3.stamp',
+ wayland_doxygen,
+ '@INPUT@',
+ ],
+ input: man_files,
+ output: 'man3',
+ build_by_default: true,
+ install: true,
+ install_dir: join_paths(get_option('prefix'), get_option('mandir')),
+)
diff --git a/doc/doxygen/xml/Client/meson.build b/doc/doxygen/xml/Client/meson.build
new file mode 100644
index 0000000..849c30d
--- /dev/null
+++ b/doc/doxygen/xml/Client/meson.build
@@ -0,0 +1,18 @@
+tgt = custom_target(
+ 'xml-Client-doc',
+ command: [
+ gen_doxygen,
+ # XXX pass doxygen path as argument
+ '--builddir=@OUTDIR@',
+ '--section=Client',
+ '--output-format=xml',
+ wayland_doxygen,
+ '@INPUT@',
+ ],
+ input: [ shared_files, client_files ],
+ output: [ 'combine.xslt', 'index.xml' ],
+ depends: [dot_png, dot_map]
+)
+
+doxygen_Client_combine_xslt = tgt[0]
+doxygen_Client_index_xml = tgt[1]
diff --git a/doc/doxygen/xml/Server/meson.build b/doc/doxygen/xml/Server/meson.build
new file mode 100644
index 0000000..4792c1b
--- /dev/null
+++ b/doc/doxygen/xml/Server/meson.build
@@ -0,0 +1,18 @@
+tgt = custom_target(
+ 'xml-Server-doc',
+ command: [
+ gen_doxygen,
+ # XXX pass doxygen path as argument
+ '--builddir=@OUTDIR@',
+ '--section=Server',
+ '--output-format=xml',
+ wayland_doxygen,
+ '@INPUT@',
+ ],
+ input: [ shared_files, server_files ],
+ output: [ 'combine.xslt', 'index.xml' ],
+ depends: [dot_png, dot_map]
+)
+
+doxygen_Server_combine_xslt = tgt[0]
+doxygen_Server_index_xml = tgt[1]
diff --git a/doc/doxygen/xml/meson.build b/doc/doxygen/xml/meson.build
new file mode 100644
index 0000000..6d55c53
--- /dev/null
+++ b/doc/doxygen/xml/meson.build
@@ -0,0 +1,22 @@
+# dot_png: list of PNG targets
+# dot_map: list of MAP targets
+foreach name, infile: dot_gv
+ dot_png += custom_target(
+ name + '.png',
+ command: [ dot, '-Tpng', '-o@OUTPUT@', '@INPUT@' ],
+ input: infile,
+ output: name + '.png',
+ install: true,
+ install_dir: join_paths(publican_install_prefix, publican_html_dir, 'images')
+ )
+
+ dot_map += custom_target(
+ name + '.map',
+ command: [ dot, '-Tcmapx_np', '-o@OUTPUT@', '@INPUT@' ],
+ input: infile,
+ output: name + '.map',
+ )
+endforeach
+
+subdir('Client')
+subdir('Server')