Commit Graph

9 Commits

Author SHA1 Message Date
Marius Vlad
8110e8de61 doc/sphinx: Add documentation for the logging/debugging framework
This details the logging/debugging framework with the latest changes,
making use of the groups added by "weston-log: Start adding
documentation" and "libweston/log: Add 'wlog' group".

Signed-off-by: Marius Vlad <marius.vlad@collabora.com>
2019-07-18 13:34:04 +03:00
Marius Vlad
284d5345ad compositor: Destroy the compositor before the log scope
Destroying the compositor after destroying the log scope will not print
out the messages in the tear down/clean-up phase of the compositor, so
add a new tear_down function which allows keeping a valid reference to
the compositor. This way we can destroy the compositor before destroying
the scope and keep the debug messages.

While at it remove the log context destroy part from the clean-up
of the compositor and make it stand on its own.

Signed-off-by: Marius Vlad <marius.vlad@collabora.com>
2019-07-18 13:34:04 +03:00
Marius Vlad
64a92265e8 doc/sphinx: No need for doxygen custom target
Unfortunate left over which was not removed once we had the script in
place to regenerate the documentation. A side-effect was the fact that
we still ran the script even if 'docs' target was called, effectively
nullifying the fact that 'docs' target was ran at all. For instance,
'install' would've been executing the script even if 'docs' target
was called before.

This removes the doxygen_target entirely and the depends of sphinx
target on it, makes building and installing docs a bit faster.

Signed-off-by: Marius Vlad <marius.vlad@collabora.com>
2019-07-01 12:20:30 +00:00
Marius Vlad
5d7877adfd doc/sphinx: Force sphinx to re-build everything as to avoid stale docs
With the introduction of the 'docs' target we make sure that we always
build the documentation, but currently breathe is unaware of the fact
that the doxygen XML database was changed in between runs. It is obvious
when changing only source code not rST bits.

This patch makes sphinx ignore the saved environment and always
rebuild the docs.

Signed-off-by: Marius Vlad <marius.vlad@collabora.com>
2019-06-28 13:39:11 +03:00
Daniel Stone
0f5bb51211 doc: Remove clang-parsing definitions
These definitions were just set to the default (off), but their presence
causes Fedora's Doxygen to emit a warning as it is not compiled with
Clang support.

Remove them as they are no-ops anyway.

Signed-off-by: Daniel Stone <daniels@collabora.com>
2019-06-26 12:27:14 +01:00
Marius Vlad
57e2cc22d2 doc/sphinx: Add 'weston_compositor', 'weston_output' and 'weston_head' API
Demonstrates how to call/use the 'doxygen*' breathe directives. Make
use of previous patches that tag symbols using 'ingroup' doxygen
command.

Signed-off-by: Marius Vlad <marius.vlad@collabora.com>
2019-06-25 14:05:54 +00:00
Marius Vlad
ae26341037 doc/sphinx: Add doxygen aliases for easier rst embedding
With these aliases we can use rST directives inside comment blocks. This
adds also a doxygen command '\rststar' where ignores the asterisk --
typical to multi-line comment blocks.

While at it, add a simple example on how to use them.

Signed-off-by: Marius Vlad <marius.vlad@collabora.com>
2019-06-25 14:05:54 +00:00
Marius Vlad
3d620bc04d doc/sphinx: Further configure doxygen
Turn warnings into errors so we can spot them immediately.

While at it: no need to generate class graphs as we're not using it and
make doxygen run quieter.

Signed-off-by: Marius Vlad <marius.vlad@collabora.com>
2019-06-25 14:05:54 +00:00
Marius Vlad
bbf6ea0b4f 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>
2019-06-25 14:05:54 +00:00