diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/doxygen/.gitignore | 1 | ||||
| -rwxr-xr-x | doc/doxygen/gen-doxygen.py | 105 | ||||
| -rw-r--r-- | doc/doxygen/meson.build | 105 | ||||
| -rw-r--r-- | doc/doxygen/xml/Client/meson.build | 18 | ||||
| -rw-r--r-- | doc/doxygen/xml/Server/meson.build | 18 | ||||
| -rw-r--r-- | doc/doxygen/xml/meson.build | 22 | ||||
| -rw-r--r-- | doc/man/meson.build | 46 | ||||
| -rw-r--r-- | doc/meson.build | 38 | ||||
| -rw-r--r-- | doc/publican/meson.build | 30 | ||||
| -rw-r--r-- | doc/publican/sources/meson.build | 113 |
10 files changed, 495 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') diff --git a/doc/man/meson.build b/doc/man/meson.build new file mode 100644 index 0000000..0fd4cec --- /dev/null +++ b/doc/man/meson.build @@ -0,0 +1,46 @@ +man_pages = [ + { + 'section': '3', + 'xml': 'wl_display_connect.xml', + 'name': 'wl_display_connect', + 'alias': 'wl_display_connect_to_fd', + } +] + +xsltproc_opts = [ + '--nonet', + '--stringparam', 'man.authors.section.enabled', '0', + '--stringparam', 'man.copyright.section.enabled', '0', + '--stringparam', 'funcsynopsis.style', 'ansi', + '--stringparam', 'man.output.quietly', '1', +] + +foreach page: man_pages + section_number = page['section'] + xml_input = page['xml'] + name = page['name'] + alias = page.get('alias', '') + + man_output = name + '.' + section_number + if alias != '' + alias_output = alias + '.' + section_number + else + alias_output = [] + endif + + man_page = custom_target( + name + '-man', + command: [ + xsltproc, + xsltproc_opts, + '-o', '@OUTPUT0@', + manpage_xsl, + '@INPUT@', + ], + input: xml_input, + output: [ man_output, alias_output ], + install: true, + install_dir: join_paths(get_option('prefix'), get_option('mandir'), 'man' + section_number), + build_by_default: true, + ) +endforeach diff --git a/doc/meson.build b/doc/meson.build new file mode 100644 index 0000000..0b46f48 --- /dev/null +++ b/doc/meson.build @@ -0,0 +1,38 @@ +dot = find_program('dot') +doxygen = find_program('doxygen') +xsltproc = find_program('xsltproc') +xmlto = find_program('xmlto') + +cmd = run_command(doxygen, '--version', check: true) +message('doxygen: ' + cmd.stdout().strip()) +vers = cmd.stdout().strip() +if vers.version_compare('< 1.6.0') + error('Doxygen 1.6 or later is required for building documentation, found @0@.'.format(vers)) +endif + +cmd = run_command(dot, '-V', check: true) +message('dot: ' + cmd.stderr().strip()) +vers = cmd.stderr().split('version')[1].strip().split(' ')[0] +if vers.version_compare('< 2.26.0') + error('Dot (Graphviz) 2.26 or later is required for building documentation, found @0@.'.format(vers)) +endif + +manpage_xsl = 'http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl' +cmd = run_command(xsltproc, '--nonet', manpage_xsl) +if cmd.returncode() != 0 + error('The style sheet for man pages providing "@0@" was not found.'.format(manpage_xsl)) +endif + +publican_install_prefix = join_paths( + get_option('prefix'), + get_option('datadir'), + 'doc', + meson.project_name(), + 'Wayland', 'en-US' +) + +publican_html_dir = 'html' + +subdir('doxygen') +subdir('man') +subdir('publican') diff --git a/doc/publican/meson.build b/doc/publican/meson.build new file mode 100644 index 0000000..898ca4f --- /dev/null +++ b/doc/publican/meson.build @@ -0,0 +1,30 @@ +merge_mapcoords_xsl = files('merge-mapcoords.xsl') + +subdir('sources') + +custom_target( + 'Wayland-docbook-html', + command: [ + xmlto, + '--skip-validation', + '--stringparam', 'chunk.section.depth=0', + '--stringparam', 'toc.section.depth=1', + '--stringparam', 'html.stylesheet=css/default.css', + '-o', '@OUTPUT@', + 'html', + '@INPUT@' + ], + input: publican_processed_main, + output: publican_html_dir, + depend_files: publican_copied_sources, + depends: [ + publican_processed_targets, + ClientAPI_xml, + ServerAPI_xml, + ProtocolSpec_xml, + ProtocolInterfaces_xml + ], + build_by_default: true, + install: true, + install_dir: publican_install_prefix +) diff --git a/doc/publican/sources/meson.build b/doc/publican/sources/meson.build new file mode 100644 index 0000000..52f3a68 --- /dev/null +++ b/doc/publican/sources/meson.build @@ -0,0 +1,113 @@ +ProtocolSpec_xml = custom_target( + 'ProtocolSpec.xml', + command: [ xsltproc, '-o', '@OUTPUT@', files('../protocol-to-docbook.xsl'), '@INPUT@' ], + input: wayland_protocol_xml, + output: 'ProtocolSpec.xml' +) + +ProtocolInterfaces_xml = custom_target( + 'ProtocolInterfaces.xml', + command: [ xsltproc, '-o', '@OUTPUT@', files('../protocol-interfaces-to-docbook.xsl'), '@INPUT@' ], + input: wayland_protocol_xml, + output: 'ProtocolInterfaces.xml' +) + +ClientAPI_combined = custom_target( + 'ClientAPI-combined', + command: [ xsltproc, '-o', '@OUTPUT@', '@INPUT@' ], + input: [ doxygen_Client_combine_xslt, doxygen_Client_index_xml ], + output: 'ClientAPI-combined.xml' +) + +to_publican_xsl = files('../doxygen-to-publican.xsl') + +ClientAPI_xml = custom_target( + 'ClientAPI.xml', + command: [ xsltproc, '-o', '@OUTPUT@', '--stringparam', 'which', 'Client', to_publican_xsl, '@INPUT@' ], + input: ClientAPI_combined, + output: 'ClientAPI.xml' +) + +ServerAPI_combined = custom_target( + 'ServerAPI-combined', + command: [ xsltproc, '-o', '@OUTPUT@', '@INPUT@' ], + input: [ doxygen_Server_combine_xslt, doxygen_Server_index_xml ], + output: 'ServerAPI-combined.xml' +) + +ServerAPI_xml = custom_target( + 'ServerAPI.xml', + command: [ xsltproc, '-o', '@OUTPUT@', '--stringparam', 'which', 'Server', to_publican_xsl, '@INPUT@' ], + input: ServerAPI_combined, + output: 'ServerAPI.xml' +) + + +publican_sources = [ + 'Wayland.ent', + # 'Wayland.xml', # handled specially + 'Book_Info.xml', + 'Author_Group.xml', + 'Foreword.xml', + 'Preface.xml', + 'Revision_History.xml', + 'Protocol.xml', + 'Xwayland.xml', + 'Compositors.xml', + 'Client.xml', + 'Server.xml' +] + +publican_processed_main = configure_file( + input: 'Wayland.xml', + output: 'Wayland.xml', + copy: true +) + +publican_copied_sources = [] +foreach src: publican_sources + publican_copied_sources += configure_file( + input: src, + output: src, + copy: true + ) +endforeach + +publican_processed_sources = [ + 'Architecture.xml', + 'Introduction.xml' +] + +publican_processed_targets = [] +foreach src: publican_processed_sources + publican_processed_targets += custom_target( + src, + command: [ xsltproc, '-o', '@OUTPUT@', '--stringparam', 'basedir', '.', merge_mapcoords_xsl, '@INPUT@' ], + input: src, + output: src + ) +endforeach + +publican_css_sources = files([ + 'css/brand.css', + 'css/common.css', + 'css/default.css', + 'css/epub.css', + 'css/print.css' +]) + +install_data( + publican_css_sources, + install_dir: join_paths(publican_install_prefix, publican_html_dir, 'css') +) + +publican_img_sources = files([ + 'images/icon.svg', + 'images/wayland.png', + 'images/xwayland-architecture.png' +]) + +install_data( + publican_img_sources, + install_dir: join_paths(publican_install_prefix, publican_html_dir, 'images') +) |