From: Bill Spitzak Date: Wed, 17 Dec 2014 03:23:03 +0000 (-0800) Subject: doc: Make it easier to add a new doxygen page X-Git-Tag: 1.6.91~7 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=6e3ad249adbf527e70d89fdb7dd25e289929f1a2;p=platform%2Fupstream%2Fwayland.git doc: Make it easier to add a new doxygen page The repetitive parts of generating the server and client documentation are merged, so it is easier to add another doxygen chapter: add a new line to $publican_sources in publican/Makefile.am, and a list of C source files to doxygen/Makefile.am. Reviewed-by: Bryce Harrington --- diff --git a/doc/doxygen/Makefile.am b/doc/doxygen/Makefile.am index 8d563f4..8c4618a 100644 --- a/doc/doxygen/Makefile.am +++ b/doc/doxygen/Makefile.am @@ -1,24 +1,24 @@ -noinst_DATA = xml/client/index.xml xml/server/index.xml +noinst_DATA = xml/Client/index.xml xml/Server/index.xml dist_noinst_DATA = wayland.doxygen.in scanned_src_files_shared = \ $(top_srcdir)/src/wayland-util.c \ $(top_srcdir)/src/wayland-util.h -scanned_src_files_client = \ +scanned_src_files_Client = \ $(scanned_src_files_shared) \ $(top_srcdir)/src/wayland-client.c \ $(top_srcdir)/src/wayland-client.h -scanned_src_files_server = \ +scanned_src_files_Server = \ $(scanned_src_files_shared) \ $(top_srcdir)/src/wayland-server.c \ $(top_srcdir)/src/wayland-server.h \ $(top_srcdir)/src/wayland-shm.c scanned_src_files_man = \ - $(scanned_src_files_server) \ + $(scanned_src_files_Server) \ $(top_srcdir)/src/wayland-client.c \ $(top_srcdir)/src/wayland-client.h @@ -28,20 +28,13 @@ scanned_src_files_man = \ dist_man3_MANS = $(shell test -d man && find man/man3 -name "wl_*.3" -printf "man/man3/%P\n") # Listing various directories that might need to be created. -alldirs := xml/client xml/server man/man3 +alldirs := xml/Client xml/Server man/man3 -xml/client/index.xml: $(scanned_src_files_client) wayland.doxygen | xml/client +xml/%/index.xml: $(scanned_src_files_%) wayland.doxygen | xml/% $(AM_V_GEN)(cat wayland.doxygen; \ echo "GENERATE_XML=YES"; \ - echo "XML_OUTPUT=xml/client"; \ - echo "INPUT= $(scanned_src_files_client)"; \ - ) | $(DOXYGEN) - - -xml/server/index.xml: $(scanned_src_files_server) wayland.doxygen | xml/server - $(AM_V_GEN)(cat wayland.doxygen; \ - echo "GENERATE_XML=YES"; \ - echo "XML_OUTPUT=xml/server"; \ - echo "INPUT= $(scanned_src_files_server)"; \ + echo "XML_OUTPUT=xml/$*"; \ + echo "INPUT= $(scanned_src_files_$*)"; \ ) | $(DOXYGEN) - man/man3/wl_display.3: $(scanned_src_files_man) wayland.doxygen | man/man3 diff --git a/doc/publican/Makefile.am b/doc/publican/Makefile.am index b4cfe82..7f0ed1b 100644 --- a/doc/publican/Makefile.am +++ b/doc/publican/Makefile.am @@ -8,9 +8,7 @@ # * ProtocolSpec.xml is generated from $(top_srcdir)/protocol/wayland.xml, # changed into docbook via XSLT and saved in $(builddir)/en-US/ # * ProtocolInterfaces.xml, same as above, uses a different XSLT -# * WaylandClientAPI.xml is generated from the doxygen output and saved in -# $(builddir)/en-US -# * WaylandServerAPI.xml is generated from the doxygen output and saved in +# * *API.xml is generated from the doxygen output and saved in # $(builddir)/en-US # * run xmlto on $(builddir)/en-US, output to $(builddir)/Wayland/en-US @@ -76,9 +74,11 @@ $(html_destdir)/images/%: $(srcdir)/sources/images/% | $(html_destdir)/images pubdir = $(docdir)/Wayland/en-US -publican_targets = $(publican_sources:$(srcdir)/sources/%=$(builddir)/en-US/%) \ - $(builddir)/en-US/ProtocolSpec.xml $(builddir)/en-US/ProtocolInterfaces.xml \ - $(builddir)/en-US/WaylandClientAPI.xml $(builddir)/en-US/WaylandServerAPI.xml +publican_targets = $(publican_sources:$(srcdir)/sources%=$(builddir)/en-US/%) \ + $(builddir)/en-US/ProtocolSpec.xml \ + $(builddir)/en-US/ProtocolInterfaces.xml \ + $(builddir)/en-US/ClientAPI.xml \ + $(builddir)/en-US/ServerAPI.xml # The Protocol.xml is purely generated and required before running publican $(builddir)/en-US/ProtocolSpec.xml: $(top_srcdir)/protocol/wayland.xml $(srcdir)/protocol-to-docbook.xsl | $(builddir)/en-US @@ -92,31 +92,23 @@ $(builddir)/en-US/ProtocolInterfaces.xml: $(top_srcdir)/protocol/wayland.xml $(s # * we don't want wayland-{server|client}_8h.xml to avoid duplicating output methods, # move it out of the way first. # * use doxygen's combine.xslt to merge the xml files into one single file +# * pipe that through the doxygen-to-publican stylesheet # * move wayland-_8h.xml back to its original location -$(builddir)/en-US/%API.xml.tmp: $(doxydir)/xml/%/index.xml | $(builddir)/en-US +$(builddir)/en-US/%API.xml: $(doxydir)/xml/%/index.xml $(srcdir)/doxygen-to-publican.xsl | $(builddir)/en-US $(AM_V_at)$(MKDIR_P) $(doxydir)/xml/$*/saved $(AM_V_at)mv $(doxydir)/xml/$*/wayland-*_8h.xml \ $(doxydir)/xml/$*/saved $(AM_V_GEN)$(XSLTPROC) $(doxydir)/xml/$*/combine.xslt \ - $(doxydir)/xml/$*/index.xml > $@ + $(doxydir)/xml/$*/index.xml | \ + $(XSLTPROC) --stringparam which $* \ + $(srcdir)/doxygen-to-publican.xsl - > $@ $(AM_V_at)mv $(doxydir)/xml/$*/saved/* \ $(doxydir)/xml/$* -# WaylandClientAPI.xml: -# merge doxygen xml files into one single file, then transform the combined XML file into docbook format -$(builddir)/en-US/WaylandClientAPI.xml: $(builddir)/en-US/clientAPI.xml.tmp $(srcdir)/doxygen-to-publican.xsl | $(builddir)/en-US - $(AM_V_GEN)$(XSLTPROC) --stringparam which Client $(srcdir)/doxygen-to-publican.xsl \ - $(builddir)/en-US/clientAPI.xml.tmp > $@ - -# WaylandServerAPI.xml: see WaylandClientAPI.xml -$(builddir)/en-US/WaylandServerAPI.xml: $(builddir)/en-US/serverAPI.xml.tmp $(srcdir)/doxygen-to-publican.xsl | $(builddir)/en-US - $(AM_V_GEN)$(XSLTPROC) --stringparam which Server $(srcdir)/doxygen-to-publican.xsl \ - $(builddir)/en-US/serverAPI.xml.tmp > $@ - # Copy the sources source files into en-US destination # This is required for out-of-source-tree build as publican does not allow us # to specify the location of the source code. -$(builddir)/en-US/%: $(srcdir)/sources/% $(builddir)/en-US/ProtocolSpec.xml $(builddir)/en-US/ProtocolInterfaces.xml $(builddir)/en-US/WaylandClientAPI.xml $(publican_sources) | $(builddir)/en-US/images +$(builddir)/en-US/%: $(srcdir)/sources/% $(publican_sources) | $(builddir)/en-US/images $(AM_V_GEN)cp -f $< $@ $(AM_V_at)chmod a+w $@ @@ -124,7 +116,7 @@ $(builddir)/en-US/%: $(srcdir)/sources/% $(builddir)/en-US/ProtocolSpec.xml $(bu $(alldirs): $(AM_V_GEN)$(MKDIR_P) $@ -CLEANFILES = $(builddir)/en-US/ProtocolSpec.xml $(builddir)/en-US/ProtocolInterfaces.xml $(builddir)/en-US/WaylandClientAPI.xml $(publican_targets) +CLEANFILES = $(publican_targets) clean-local: $(AM_V_at)rm -fr $(builddir)/en-US diff --git a/doc/publican/doxygen-to-publican.xsl b/doc/publican/doxygen-to-publican.xsl index 53fc60f..47bdc5a 100644 --- a/doc/publican/doxygen-to-publican.xsl +++ b/doc/publican/doxygen-to-publican.xsl @@ -29,9 +29,8 @@ Following is the Wayland library classes for the - - (libwayland-). This appendix describes in detail + libwayland-. This appendix describes in detail the library's methods and their helpers, aiming implementors who are building a Wayland . diff --git a/doc/publican/sources/Wayland.xml b/doc/publican/sources/Wayland.xml index bdf8930..5ae90bb 100644 --- a/doc/publican/sources/Wayland.xml +++ b/doc/publican/sources/Wayland.xml @@ -12,7 +12,7 @@ - - + +