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

[Jon A. Cruz]

On 07/07/2015 05:35 AM, Pekka Paalanen wrote:
> 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?

It could be refined to do so. However there are a few things to check
about overlapping directories, in-tree vs. out-of-tree builds,
dependency timestamps, etc. that take a little consideration.

The main reason is to just start with output that doesn't overlap
sources so as to avoid some initial mistakes. Some projects like to keep
separated output, some does not. Also we probably need to decide if any
should end up installed.

>> +
>> +$(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.
> 

Yes. It is a bit quick-n-dirty for the first cut. Generally developers
will be much easier to speak up about things they don't like with docs
if it is trivial for them to build. Talking about possibilities shifts
to be much faster once there is a concrete first implementation.

In general I'm fairly flexible about how good project docs might end up.
The only point I really care about is that they are generated and
automatically kept up to date with the source.

>> +
>> +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/?
> 

Done.

>>  
>>  	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.
> 

Done.

> 
> Thanks,
> pq
> _______________________________________________
> wayland-devel mailing list
> wayland-devel at lists.freedesktop.org
> http://lists.freedesktop.org/mailman/listinfo/wayland-devel
> 

-- 
Jon A. Cruz - Senior Open Source Developer
Samsung Open Source Group
jonc at osg.samsung.com