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>dev
parent
71309894f3
commit
bbf6ea0b4f
@ -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 |
File diff suppressed because it is too large
Load Diff
@ -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` |
@ -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, |
||||
) |
@ -0,0 +1,2 @@ |
||||
#!/bin/sh |
||||
@DOXYGEN_CMD@ @DOXYGEN_CONF@ && @SPHINX_CMD@ -W -q -j auto @SRCDIR@ @OUTDIR@ |
@ -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. |
@ -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`. |
@ -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`. |
@ -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 |
@ -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. |
@ -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') |
Loading…
Reference in new issue