build: Add sphinx/breathe support for generating documentation

This is adds basic configuration files for doxygen and for breathe,
which is a doxygen-to-sphinx bridge that can document C symbols.

Breathe is configured with default project 'weston' and implicitly adds
:members: and :undoc-members: to breathe configuration options.
This allows a shorter way to call breathe directives without the need
specify the project and also to display implicitly all the members,
documented or not.

A 'docs' run_target to force the docs to be re-built has been added.
Initially (the first time the build system is ran) the documentation
will automatically be built, but later re-builds will require the use of
the 'docs' target. This avoid further delays in building weston but in
the same time allows the possiblity to update/improve the documentation
bits to those who want that.

Signed-off-by: Marius Vlad <marius.vlad@collabora.com>

doc/sphinx/conf.py.in

@@ -0,0 +1,201 @@
+# -*- coding: utf-8 -*-
+#
+# Configuration file for the Sphinx documentation builder.
+#
+# This file does only contain a selection of the most common options. For a
+# full list see the documentation:
+# http://www.sphinx-doc.org/en/master/config
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# 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
+import sphinx
+
+sys.path.append(os.path.abspath('sphinxext'))
+
+# -- Project information -----------------------------------------------------
+
+project = u'weston'
+copyright = u'2019, Weston community'
+author = u'Weston community '
+
+
+# The short X.Y version
+version = u''
+# The full version, including alpha/beta/rc tags
+release = u'@VERSION@'
+
+
+# -- General configuration ---------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#
+needs_sphinx = '2.1.0'
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.intersphinx',
+    'sphinx.ext.autosectionlabel',
+    'sphinx.ext.todo',
+    'sphinx.ext.coverage',
+    'sphinx.ext.mathjax',
+    'sphinx.ext.ifconfig',
+    'sphinx.ext.viewcode',
+    'breathe',
+]
+
+breathe_projects = { "weston": "@BUILD_ROOT@/xml/" }
+breathe_default_members = ('members', 'undoc-members')
+breathe_default_project = "weston"
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+source_suffix = ['.rst' ]
+
+# The master toctree document.
+master_doc = 'index'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = None
+
+# 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 = []
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = None
+
+# default domain
+primary_domain = 'cpp'
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'sphinx_rtd_theme'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+#
+# html_theme_options = {}
+
+# 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']
+
+# Custom sidebar templates, must be a dictionary that maps document names
+# to template names.
+#
+# The default sidebars (for documents that don't match any pattern) are
+# defined by theme itself.  Builtin themes are using these templates by
+# default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
+# 'searchbox.html']``.
+#
+# html_sidebars = {}
+
+
+# -- Options for HTMLHelp output ---------------------------------------------
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'weston'
+
+
+# -- Options for LaTeX output ------------------------------------------------
+
+latex_elements = {
+    # The paper size ('letterpaper' or 'a4paper').
+    #
+    # 'papersize': 'letterpaper',
+
+    # The font size ('10pt', '11pt' or '12pt').
+    #
+    # 'pointsize': '10pt',
+
+    # Additional stuff for the LaTeX preamble.
+    #
+    # 'preamble': '',
+
+    # Latex figure (float) alignment
+    #
+    # 'figure_align': 'htbp',
+}
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title,
+#  author, documentclass [howto, manual, or own class]).
+latex_documents = [
+    (master_doc, 'weston.tex', u'Weston Documentation',
+     u'Weston community', 'manual'),
+]
+
+
+# -- Options for manual page output ------------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+    (master_doc, 'weston', u'Weston Documentation',
+     [author], 1)
+]
+
+
+# -- Options for Texinfo output ----------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+#  dir menu entry, description, category)
+texinfo_documents = [
+    (master_doc, 'weston', u'Wweston Documentation',
+     author, 'Weston community', 'Weston Documentation'
+     'Miscellaneous'),
+]
+
+
+# -- Options for Epub output -------------------------------------------------
+
+# Bibliographic Dublin Core info.
+epub_title = project
+
+# The unique identifier of the text. This can be a ISBN number
+# or the project homepage.
+#
+# epub_identifier = ''
+
+# A unique identification for the text.
+#
+# epub_uid = ''
+
+# A list of files that should not be packed into the epub file.
+epub_exclude_files = ['search.html']
+
+
+# -- Extension configuration -------------------------------------------------
+
+# -- Options for intersphinx extension ---------------------------------------
+
+# Example configuration for intersphinx: refer to the Python standard library.
+intersphinx_mapping = {'https://docs.python.org/3': None}
+
+# -- Options for todo extension ----------------------------------------------
+
+# If true, `todo` and `todoList` produce output, else they produce nothing.
+todo_include_todos = True

doc/sphinx/index.rst

@@ -0,0 +1,32 @@
+Welcome to Weston documentation!
+================================
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   toc/libweston.rst
+
+Weston
+------
+
+Weston is the reference implementation of a Wayland compositor, as well as a
+useful environment in and of itself.
+
+Out of the box, Weston provides a very basic desktop, or a full-featured
+environment for non-desktop uses such as automotive, embedded, in-flight,
+industrial, kiosks, set-top boxes and TVs. It also provides a library allowing
+other projects to build their own full-featured environments on top of Weston's
+core.
+
+The core focus of Weston is correctness and reliability. Weston aims to be lean
+and fast, but more importantly, to be predictable. Whilst Weston does have
+known bugs and shortcomings, we avoid unknown or variable behaviour as much as
+possible, including variable performance such as occasional spikes in frame
+display time.
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`search`

doc/sphinx/meson.build

@@ -0,0 +1,96 @@
+sphinx = find_program('sphinx-build', required: true)
+doxygen = find_program('doxygen', required: true)
+breathe = find_program('breathe-apidoc', required: true)
+
+sphinx_c = run_command(sphinx, '--version')
+breathe_c = run_command(breathe, '--version')
+doxygen_c = run_command(doxygen, '--version')
+
+sphinx_v = sphinx_c.stdout().split(' ')[1].strip()
+breathe_v = breathe_c.stdout().split(' ')[2].strip()
+doxygen_v = doxygen_c.stdout().strip()
+
+if sphinx_v.version_compare('< 2.1.0')
+	error('Use at least sphinx version 2.1.0, found ' + sphinx_v)
+endif
+
+if breathe_v.version_compare('< 4.11')
+	error('Use at least breathe version 4.11, found ' + breathe_v)
+endif
+
+if doxygen_v.version_compare('< 1.8')
+	error('Use at least doxygen version 1.8, found ' + doxygen_v)
+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
+)
+
+doxy_conf_data = configuration_data()
+doxy_conf_data.set('SRC_ROOT', meson.source_root())
+doxy_conf_data.set('OUTPUT_DIR', doxygen_database)
+doxygen_conf_weston = configure_file(
+		input: 'doxygen.ini.in',
+		output: 'doxygen.ini',
+		configuration: doxy_conf_data
+)
+
+script_data = configuration_data()
+script_data.set('SRCDIR', meson.current_build_dir())
+script_data.set('OUTDIR', meson.current_build_dir() + '/doc')
+script_data.set('DOXYGEN_CONF', meson.current_build_dir() + '/doxygen.ini')
+script_data.set('DOXYGEN_CMD', doxygen.path())
+script_data.set('SPHINX_CMD', sphinx.path())
+script_doxy_sphinx = configure_file(
+	input: 'run_doxygen_sphinx.sh.in',
+	output: 'run_doxygen_sphinx.sh',
+	configuration: script_data
+)
+
+doxygen_target = custom_target(
+			'weston-doc-doxygen',
+			command: [ doxygen, doxygen_conf_weston ],
+			output: 'doxygen_doc',
+			build_by_default: false
+)
+
+# 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
+subdir('toc')
+
+sphinx_doc = custom_target(
+		'weston-doc-breathe',
+		command: script_doxy_sphinx,
+		output: 'doc',
+		build_by_default: true,
+		depends: doxygen_target
+)
+
+# we need this because we will have a stale 'doc' 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', 'weston'),
+	strip_directory: true,
+)

doc/sphinx/run_doxygen_sphinx.sh.in

@@ -0,0 +1,2 @@
+#!/bin/sh
+@DOXYGEN_CMD@ @DOXYGEN_CONF@ && @SPHINX_CMD@ -W -q -j auto @SRCDIR@ @OUTDIR@

doc/sphinx/toc/libweston.rst

@@ -0,0 +1,46 @@
+Libweston
+=========
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   libweston/compositor.rst
+   libweston/head.rst
+   libweston/output.rst
+
+`Libweston` is an effort to separate the re-usable parts of Weston into a
+library. `Libweston` provides most of the boring and tedious bits of correctly
+implementing core Wayland protocols and interfacing with input and output
+systems, so that people who just want to write a new "Wayland window manager"
+(WM) or a small desktop environment (DE) can focus on the WM part.
+
+Libweston was first introduced in Weston 1.12, and is expected to continue
+evolving through many Weston releases before it achieves a stable API and
+feature completeness.
+
+`Libweston`'s primary purpose is exporting an API for creating Wayland
+compositors. Libweston's secondary purpose is to export the weston_config API
+so that third party plugins and helper programs can read :file:`weston.ini` if
+they want to. However, these two scopes are orthogonal and independent. At no
+point will the compositor functionality use or depend on the weston_config
+functionality.
+
+Further work
+------------
+
+In current form, `libweston` is an amalgam of various APIs mashed together and
+currently it needs a large clean-up and re-organization and possibly, a split
+into class-specific files. The documentation only provide the public
+API and not the private API used inside `libweston` or other functionality
+required in the core internals of the library.
+
+With that in mind we see the following steps needed to achieve that:
+
+- migrate everything that should not reside in the public API (for instance,
+  the doxygen **\\internal** command is a clear indication that that symbol
+  should not be present in the public API) to private headers.
+- if needed be, create class-specific files, like **input** and **output**
+  which should tackle specific functionality, and allows to write the
+  documentation parts much easier, and provides clarity for `libweston`
+  users when they'd read it.

doc/sphinx/toc/libweston/compositor.rst

@@ -0,0 +1,7 @@
+Compositor
+==========
+
+:type:`weston_compositor` represents the core object of the library, which
+aggregates all the other objects and maintains their state. You can create it
+using :func:`weston_compositor_create`, while for destroying it and releasing all
+the resources associated with it, you should use :func:`weston_compositor_destroy`.

doc/sphinx/toc/libweston/head.rst

@@ -0,0 +1,18 @@
+Head
+====
+
+A head usually refers to a monitor, but it can also refer to an output window
+in case of a nested compositor. A :type:`weston_output` is responsible for
+driving a :type:`weston_head`. :type:`weston_head` should be initialized using
+:func:`weston_head_init`, and shall be released using
+:func:`weston_head_release`.
+
+.. note::
+
+   :func:`weston_head_init` and :func:`weston_head_release` belong to the
+   private/internal backend API and should be moved accordingly once that
+   section has been created.
+
+A :type:`weston_head` must be attached/detached from a :type:`weston_output`.
+To that purpose you can use :func:`weston_output_attach_head`, respectively
+:func:`weston_head_detach`.

doc/sphinx/toc/libweston/meson.build

@@ -0,0 +1,6 @@
+# you need to add here any files you add to the toc directory as well
+files = [ 'compositor.rst', 'head.rst', 'output.rst' ]
+
+foreach file : files
+	configure_file(input: file, output: file, copy: true)
+endforeach

doc/sphinx/toc/libweston/output.rst

@@ -0,0 +1,10 @@
+Output
+======
+
+With at least a :type:`weston_head` attached, you can construct a
+:type:`weston_output` object which can be used by the compositor, by enabling
+the output using :func:`weston_output_enable`. The output **must not** be
+already enabled.
+
+The reverse operation, :func:`weston_output_disable`, should be used when there's
+a need to reconfigure the output or it will be destroyed.

doc/sphinx/toc/meson.build

@@ -0,0 +1,8 @@
+# you need to add here any files you add to the toc directory as well
+files = [ 'libweston.rst' ]
+
+foreach file : files
+	configure_file(input: file, output: file, copy: true)
+endforeach
+
+subdir('libweston')

meson.build

@@ -161,5 +161,8 @@ subdir('man')
 
 configure_file(output: 'config.h', configuration: config_h)
 
-
+if get_option('doc')
-# TODO: process doc/doxygen/*.doxygen.in
+	subdir('doc/sphinx')
+else
+	message('Documentation will not be built. Use -Ddoc to build it.')
+endif

meson_options.txt

@@ -204,3 +204,9 @@ option(
 	value: true,
 	description: 'Tests: output JUnit XML results'
 )
+option(
+	'doc',
+	type: 'boolean',
+	value: false,
+	description: 'Generate documentation'
+)