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

[Pekka Paalanen]

On Wed, 15 Jul 2015 19:29:37 -0700
"Jon A. Cruz" <jonc at osg.samsung.com> wrote:

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

In that case, if you really want separate dirs, name them so that a
user knows where to look. For example: doc-src and doc-output.
Something that makes it clear where I will find the files to edit, and
where are the files that were generated when I want to just read the
results.

In Wayland, I always struggle with finding the final doc build products.

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

The README notes do help for the above.

Anyway, this isn't really a blocker I think, so I see if I can merge
the v7 patches as is.


Thanks,
pq