docs: Re-enable generating the reference manual

gtk-doc support was removed around 3 years ago with commit 7dc0b0e6.
Now that we have Meson and [MRs related to documentation], it makes
sense to re-enable this, so people who want to use libmutter can do so
without having to actually dive in the code.

[MRs related to documentation]: https://gitlab.gnome.org/GNOME/mutter/merge_requests/269
This commit is contained in:
Niels De Graef 2019-01-17 09:29:00 +01:00 committed by Niels De Graef
parent 46453c7a7d
commit 83fd21f759
8 changed files with 259 additions and 2 deletions

100
doc/meson.build Normal file
View File

@ -0,0 +1,100 @@
# manpage
subdir('man')
# Reference manual
subdir('xml')
version_conf = configuration_data()
version_conf.set('VERSION', meson.project_version())
version_xml = configure_file(
input: 'version.xml.in',
output: 'version.xml',
configuration: version_conf
)
reference_ignored_headers = [
'config.h',
'bell.h',
'boxes-private.h',
'compositor-private.h',
'core.h',
'constraints.h',
'display-private.h',
'frame.h',
'frames.h',
'group-private.h',
'keybindings-private.h',
'main.h',
'meta-backend-private.h',
'meta-background-private.h',
'meta-barrier-private.h',
'meta-dnd-actor-private.h',
'meta-dnd-private.h',
'meta-feedback-actor-private.h',
'meta-gesture-tracker-private.h',
'meta-idle-monitor-private.h',
'meta-input-mapper-private.h',
'meta-input-settings-private.h',
'meta-monitor-manager-private.h',
'meta-remote-access-controller-private.h',
'meta-settings-private.h',
'meta-shaped-texture-private.h',
'meta-stage-private.h',
'meta-wayland-private.h',
'meta-window-actor-private.h',
'meta-window-group-private.h',
'meta-xwayland-private.h',
'meta-xwayland-selection-private.h',
'theme-private.h',
'util-private.h',
'window-private.h',
'window-x11-private.h',
'workspace-private.h',
# Test headers
'meta-backend-test.h',
'meta-monitor-manager-test.h',
'meta-wayland-egl-stream.h',
'meta-wayland-inhibit-shortcuts.h',
'meta-wayland-text-input.h',
'meta-xwayland-grab-keyboard.h',
]
# Make sure we ignore the wayland headers
if have_wayland
foreach proto : wayland_protocols
protocol_name = proto[0]
protocol_type = proto[1]
if protocol_type == 'stable'
output_base = protocol_name
elif protocol_type == 'private'
output_base = protocol_name
elif protocol_type == 'third-party'
output_base = protocol_name
else
protocol_version = proto[2]
output_base = '@0@-@1@-@2@'.format(protocol_name,
protocol_type,
protocol_version)
endif
proto_header = '@0@-server-protocol.h'.format(output_base)
reference_ignored_headers += proto_header
endforeach
endif
gnome.gtkdoc(meson.project_name(),
main_sgml: 'mutter-docs.sgml',
src_dir: [
include_directories('../src'),
],
dependencies: _libmutter_public_symbols_dep,
gobject_typesfile: 'mutter.types',
scan_args: [
'--rebuild-types',
'--ignore-headers=' + ' '.join(reference_ignored_headers),
'--ignore-decorators=META_EXPORT|META_EXPORT_TEST',
],
install: true,
)

110
doc/mutter-docs.sgml Normal file
View File

@ -0,0 +1,110 @@
<?xml version="1.0"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"
[
<!ENTITY % local.common.attrib "xmlns:xi CDATA #FIXED 'http://www.w3.org/2003/XInclude'">
<!ENTITY % gtkdocentities SYSTEM "xml/gtkdocentities.ent">
%gtkdocentities;
]>
<book id="index">
<bookinfo>
<title>Mutter Reference Manual</title>
<releaseinfo>
For &package_string;.
The latest version of this documentation can be found on-line at
<ulink role="online-location" url="http://[SERVER]/&package_name;/index.html">http://[SERVER]/&package_name;/</ulink>.
</releaseinfo>
</bookinfo>
<chapter>
<title>General</title>
<xi:include href="xml/meta-backend.xml"/>
<xi:include href="xml/meta-clutter-backend-native.xml"/>
<xi:include href="xml/meta-renderer.xml"/>
<xi:include href="xml/meta-stage.xml"/>
</chapter>
<chapter>
<title>Clutter actors</title>
<xi:include href="xml/meta-window-actor.xml"/>
<xi:include href="xml/meta-window-group.xml"/>
<xi:include href="xml/meta-background-actor.xml"/>
<xi:include href="xml/meta-background-group.xml"/>
<xi:include href="xml/meta-surface-actor.xml"/>
<xi:include href="xml/meta-shaped-texture.xml"/>
</chapter>
<chapter>
<title>Plugins</title>
<xi:include href="xml/meta-plugin.xml"/>
<xi:include href="xml/meta-plugin-manager.xml"/>
</chapter>
<chapter>
<title>Cursor management</title>
<xi:include href="xml/meta-cursor-tracker.xml"/>
<xi:include href="xml/meta-cursor.xml"/>
<xi:include href="xml/meta-cursor-renderer.xml"/>
<xi:include href="xml/meta-pointer-constraint.xml"/>
</chapter>
<chapter>
<title>Monitor management</title>
<xi:include href="xml/meta-monitor-manager.xml"/>
<xi:include href="xml/meta-monitor-manager-dummy.xml"/>
<xi:include href="xml/meta-monitor-config-manager.xml"/>
<xi:include href="xml/meta-logical-monitor.xml"/>
<xi:include href="xml/meta-monitor.xml"/>
<xi:include href="xml/meta-monitor-transform.xml"/>
</chapter>
<chapter>
<title>X11</title>
<xi:include href="xml/meta-backend-x11.xml"/>
<xi:include href="xml/meta-monitor-manager-xrandr.xml"/>
<xi:include href="xml/meta-window-actor-x11.xml"/>
<xi:include href="xml/meta-surface-actor-x11.xml"/>
</chapter>
<chapter>
<title>Native / Wayland</title>
<xi:include href="xml/meta-backend-native.xml"/>
<xi:include href="xml/meta-monitor-manager-kms.xml"/>
<xi:include href="xml/meta-renderer-native.xml"/>
<xi:include href="xml/meta-window-actor-wayland.xml"/>
<xi:include href="xml/meta-surface-actor-wayland.xml"/>
</chapter>
<chapter>
<title>Screencast</title>
<xi:include href="xml/meta-screen-cast.xml"/>
<xi:include href="xml/meta-screen-cast-session.xml"/>
<xi:include href="xml/meta-screen-cast-window.xml"/>
<xi:include href="xml/meta-screen-cast-stream.xml"/>
<xi:include href="xml/meta-screen-cast-window-stream.xml"/>
<xi:include href="xml/meta-screen-cast-monitor-stream.xml"/>
<xi:include href="xml/meta-screen-cast-stream-src.xml"/>
<xi:include href="xml/meta-screen-cast-window-stream-src.xml"/>
<xi:include href="xml/meta-screen-cast-monitor-stream-src.xml"/>
</chapter>
<chapter>
<title>Remote desktop</title>
<xi:include href="xml/meta-remote-desktop.xml"/>
<xi:include href="xml/meta-dbus-remote-desktop.xml"/>
</chapter>
<chapter id="object-tree">
<title>Object Hierarchy</title>
<xi:include href="xml/tree_index.sgml"/>
</chapter>
<index id="api-index-full">
<title>API Index</title>
<xi:include href="xml/api-index-full.xml"><xi:fallback /></xi:include>
</index>
<index id="deprecated-api-index" 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>

1
doc/version.xml.in Normal file
View File

@ -0,0 +1 @@
@VERSION@

View File

@ -0,0 +1,7 @@
<!ENTITY package @PACKAGE@>
<!ENTITY package_bugreport @PACKAGE_BUGREPORT@>
<!ENTITY package_name @PACKAGE_NAME@>
<!ENTITY package_string @PACKAGE_STRING@>
<!ENTITY package_tarname @PACKAGE_TARNAME@>
<!ENTITY package_url @PACKAGE_URL@>
<!ENTITY package_version @PACKAGE_VERSION@>

13
doc/xml/meson.build Normal file
View File

@ -0,0 +1,13 @@
gtkdoc_entities_cdata = configuration_data()
gtkdoc_entities_cdata.set_quoted('PACKAGE', meson.project_name())
gtkdoc_entities_cdata.set_quoted('PACKAGE_BUGREPORT', 'https://gitlab.gnome.org/GNOME/mutter/issues/new')
gtkdoc_entities_cdata.set_quoted('PACKAGE_NAME', meson.project_name())
gtkdoc_entities_cdata.set_quoted('PACKAGE_STRING', '@0@ - @1@'.format(meson.project_name(), meson.project_version()))
gtkdoc_entities_cdata.set_quoted('PACKAGE_TARNAME', 'mutter.tar.xz')
gtkdoc_entities_cdata.set_quoted('PACKAGE_URL', 'https://gitlab.gnome.org/GNOME/mutter/')
gtkdoc_entities_cdata.set_quoted('PACKAGE_VERSION', meson.project_version())
configure_file(
input: 'gtkdocentities.ent.in',
output: 'gtkdocentities.ent',
configuration: gtkdoc_entities_cdata,
)

View File

@ -370,7 +370,7 @@ subdir('clutter')
subdir('data') subdir('data')
subdir('src') subdir('src')
subdir('po') subdir('po')
subdir('doc/man') subdir('doc')
output = [ output = [
'', '',

View File

@ -20,7 +20,7 @@
*/ */
/** /**
* SECTION:cursor-tracker * SECTION:meta-cursor-tracker
* @title: MetaCursorTracker * @title: MetaCursorTracker
* @short_description: Mutter cursor tracking helper. Originally only * @short_description: Mutter cursor tracking helper. Originally only
* tracking the cursor image, now more of a "core * tracking the cursor image, now more of a "core

View File

@ -778,6 +778,32 @@ libmutter_dep = declare_dependency(
], ],
) )
# Interal library for gtk-doc (we need symbol visibility)
_libmutter_public_symbols = library(libmutter_name + '-public-symbols',
sources: [
mutter_sources,
mutter_built_sources,
],
include_directories: mutter_includes,
c_args: mutter_c_args,
dependencies: [
libmutter_cogl_dep,
libmutter_clutter_dep,
mutter_deps,
],
)
_libmutter_public_symbols_dep = declare_dependency(
link_with: _libmutter_public_symbols,
include_directories: mutter_includes,
sources: mutter_built_sources,
dependencies: [
libmutter_cogl_dep,
libmutter_clutter_dep,
mutter_deps,
],
)
executable('mutter', executable('mutter',
sources: [ sources: [
files('core/mutter.c'), files('core/mutter.c'),