[PATCH weston v6 4/4] Adding doxygen setup and info for the testing framework.

[Pekka Paalanen]

On Thu,  2 Jul 2015 23:36:47 -0700
"Jon A. Cruz" <jonc at osg.samsung.com> wrote:

> Signed-off-by: Jon A. Cruz <jonc at osg.samsung.com>
> ---
>  .gitignore                     |  2 +
>  Makefile.am                    | 22 +++++++++++
>  configure.ac                   | 20 ++++++++++
>  doc/doxygen/devtools.dox       | 51 +++++++++++++++++++++++++
>  doc/doxygen/tooldev.doxygen.in | 11 ++++++
>  doc/doxygen/tools.dox          | 31 +++++++++++++++
>  doc/doxygen/tools.doxygen.in   | 10 +++++
>  doc/doxygen/tools_arch_new.gv  | 85 ++++++++++++++++++++++++++++++++++++++++++
>  doc/doxygen/tools_arch_old.gv  | 53 ++++++++++++++++++++++++++
>  9 files changed, 285 insertions(+)
>  create mode 100644 doc/doxygen/devtools.dox
>  create mode 100644 doc/doxygen/tooldev.doxygen.in
>  create mode 100644 doc/doxygen/tools.dox
>  create mode 100644 doc/doxygen/tools.doxygen.in
>  create mode 100644 doc/doxygen/tools_arch_new.gv
>  create mode 100644 doc/doxygen/tools_arch_old.gv
> 
> diff --git a/.gitignore b/.gitignore
> index 2e6a9e2..b13bf55 100644
> --- a/.gitignore
> +++ b/.gitignore
> @@ -29,6 +29,8 @@ cscope.out
>  /config.sub
>  /configure
>  /depcomp
> +/docs/developer
> +/docs/tools
>  /install-sh
>  /libtool
>  /ltmain.sh
> diff --git a/Makefile.am b/Makefile.am
> index 42f0ed4..e5c7da9 100644
> --- a/Makefile.am
> +++ b/Makefile.am
> @@ -1056,6 +1056,7 @@ WESTON_LOG_COMPILER = $(srcdir)/tests/weston-tests-env
>  
>  clean-local:
>  	-rm -rf logs
> +	-rm -rf $(DOCDIRS)
>  
>  # To remove when automake 1.11 support is dropped
>  export abs_builddir
> @@ -1351,6 +1352,27 @@ EXTRA_DIST +=					\
>  
>  CLEANFILES += $(man_MANS)
>  
> +if ENABLE_DEVDOCS
> +DOXYGEN_INDICES = docs/developer/html/index.html docs/tools/html/index.html
> +
> +docs/developer/html/index.html: doc/doxygen/tooldev.doxygen | docs/developer
> +	cd doc/doxygen && $(DOXYGEN) tooldev.doxygen
> +
> +docs/tools/html/index.html: doc/doxygen/tools.doxygen | docs/tools
> +	cd doc/doxygen && $(DOXYGEN) tools.doxygen
> +endif
> +
> +DOCDIRS =		\
> +	docs/developer	\
> +	docs/tools

Is it intentional to have both doc and docs dirs?
Wouldn't these go to doc?

> +
> +$(DOCDIRS):
> +	$(MKDIR_P) $@
> +
> +.PHONY: doc $(DOXYGEN_INDICES)

The index files are phony?

Aah, you don't have dependencies? Because doxygen finds them on its
own, which makes it a bit difficult to maintain a good dependency list,
and if one changed, you'd need to generate everything anyway?

I was wondering why 'make doc' was not part of 'make', but this explains.

Now that I know why (right?), it's fine.

> +
> +doc: $(DOXYGEN_INDICES)
> +
>  protocol/%-protocol.c : $(top_srcdir)/protocol/%.xml
>  	$(AM_V_GEN)$(MKDIR_P) $(dir $@) && $(wayland_scanner) code < $< > $@
>  
> diff --git a/configure.ac b/configure.ac
> index b67df39..4852e2c 100644
> --- a/configure.ac
> +++ b/configure.ac
> @@ -61,6 +61,25 @@ AC_CHECK_FUNCS([mkostemp strchrnul initgroups posix_fallocate])
>  
>  COMPOSITOR_MODULES="wayland-server >= 1.8.0 pixman-1 >= 0.25.2"
>  
> +AC_CONFIG_FILES([doc/doxygen/tools.doxygen doc/doxygen/tooldev.doxygen])
> +
> +AC_ARG_ENABLE(devdocs,
> +	      AS_HELP_STRING([--disable-devdocs],
> +			     [do not build developer documentation]),,
> +	      enable_devdocs=auto)
> +if test "x$enable_devdocs" != "xno"; then
> +	AC_CHECK_PROGS([DOXYGEN], [doxygen])
> +	if test "x$DOXYGEN" = "x" -a "x$enable_devdocs" = "xyes"; then
> +		AC_MSG_ERROR([Developer documentation explicitly requested, but Doxygen couldn't be found])
> +	fi
> +	if test "x$DOXYGEN" != "x"; then
> +		enable_devdocs=yes
> +	else
> +		enable_devdocs=no
> +	fi
> +fi
> +AM_CONDITIONAL(ENABLE_DEVDOCS, test "x$enable_devdocs" = "xyes")
> +
>  AC_ARG_ENABLE(egl, [  --disable-egl],,
>                enable_egl=yes)
>  AM_CONDITIONAL(ENABLE_EGL, test x$enable_egl = xyes)
> @@ -550,6 +569,7 @@ AC_MSG_RESULT([
>  
>  	Build wcap utility		${enable_wcap_tools}
>  	Build Fullscreen Shell		${enable_fullscreen_shell}
> +	Build developer documentation	${enable_devdocs}

This is a little misleading, because it does not actually build it
without an explicit 'make doc'.

And if it's "no", then 'make doc' is just a silent no-op, right? Not
even a failure.

But I understand you don't want to hook it up to 'make', because every
'make' would then rebuild all docs.

Maybe just s/Build/Enable/?

>  
>  	weston-launch utility		${enable_weston_launch}
>  	systemd-login support		${have_systemd_login}

I looked at the generated docs and graphs, and they look fine to me.


Would be nice if this patch updated README with a note of 'make doc'
and pointing to the generated index.html files.


Thanks,
pq