[5/5] doc: Make it easier to add a new doxygen page

Submitted by Bill Spitzak on Dec. 10, 2014, 1:01 a.m.

Details

Message ID 1418173273-27576-6-git-send-email-spitzak@gmail.com
State Superseded
Headers show

Not browsing as part of any series.

Commit Message

Bill Spitzak Dec. 10, 2014, 1:01 a.m.
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.
---
 doc/doxygen/Makefile.am              |   23 ++++++++--------------
 doc/publican/Makefile.am             |   35 ++++++++++++++--------------------
 doc/publican/doxygen-to-publican.xsl |    5 ++---
 doc/publican/sources/Wayland.xml     |    4 ++--
 4 files changed, 26 insertions(+), 41 deletions(-)

Patch hide | download patch | download mbox

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 c109795..ac32c03 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
 
@@ -29,7 +27,11 @@  publican_sources = \
 	$(srcdir)/sources/images/icon.svg  \
 	$(srcdir)/sources/images/wayland-architecture.png \
 	$(srcdir)/sources/images/wayland.png  \
-	$(srcdir)/sources/images/x-architecture.png
+	$(srcdir)/sources/images/x-architecture.png \
+	en-US/ProtocolSpec.xml \
+	en-US/ProtocolInterfaces.xml \
+	en-US/ClientAPI.xml \
+	en-US/ServerAPI.xml
 
 css_sources = \
 	$(srcdir)/sources/css/brand.css \
@@ -76,9 +78,7 @@  $(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/%)
 
 # 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
@@ -94,28 +94,21 @@  $(builddir)/en-US/ProtocolInterfaces.xml: $(top_srcdir)/protocol/wayland.xml $(s
 # * use doxygen's combine.xslt to merge the xml files into one single file
 # * move wayland-<foo>_8h.xml back to its original location
 $(builddir)/en-US/%API.xml.tmp: $(doxydir)/xml/%/index.xml | $(builddir)/en-US
-	$(AM_V_at)mv $(doxydir)/xml/$*/wayland-$*_8h.xml \
+	$(AM_V_at)mv $(doxydir)/xml/$*/wayland-*_8h.xml \
 		$(doxydir)/xml/
 	$(AM_V_GEN)$(XSLTPROC) $(doxydir)/xml/$*/combine.xslt \
 		$(doxydir)/xml/$*/index.xml > $@
-	$(AM_V_at)mv $(doxydir)/xml/wayland-$*_8h.xml \
+	$(AM_V_at)mv $(doxydir)/xml/wayland-*_8h.xml \
 		$(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 > $@
+$(builddir)/en-US/%API.xml: $(builddir)/en-US/%API.xml.tmp $(srcdir)/doxygen-to-publican.xsl
+	$(AM_V_GEN)$(XSLTPROC) --stringparam which $* $(srcdir)/doxygen-to-publican.xsl \
+		$@.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 $@
 
@@ -123,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 @@ 
 
     <para>
       Following is the Wayland library classes for the
-      <xsl:value-of select="$which"/>
-      (<emphasis>libwayland-<xsl:value-of select="translate($which,
-      'SC', 'sc')"/></emphasis>).  This appendix describes in detail
+      <emphasis>libwayland-<xsl:value-of select="translate($which,
+      'SC', 'sc')"/></emphasis>.  This appendix describes in detail
       the library's methods and their helpers, aiming implementors who
       are building a Wayland <xsl:value-of select="translate($which,
       'SC', 'sc')"/>.
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 @@ 
   <xi:include href="Architecture.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
   <xi:include href="Protocol.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
   <xi:include href="ProtocolSpec.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
-  <xi:include href="WaylandClientAPI.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
-  <xi:include href="WaylandServerAPI.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
+  <xi:include href="ClientAPI.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
+  <xi:include href="ServerAPI.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
 </book>
 

Comments

On Tue,  9 Dec 2014 17:01:13 -0800
Bill Spitzak <spitzak@gmail.com> wrote:

> 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.
> ---
>  doc/doxygen/Makefile.am              |   23 ++++++++--------------
>  doc/publican/Makefile.am             |   35 ++++++++++++++--------------------
>  doc/publican/doxygen-to-publican.xsl |    5 ++---
>  doc/publican/sources/Wayland.xml     |    4 ++--
>  4 files changed, 26 insertions(+), 41 deletions(-)
> 


Hi,

this patch does not survive a 'make distcheck':

make[4]: Leaving directory '/home/pq/git/wayland/wayland-1.6.90/_build/doc/doxygen'
Making all in publican
make[4]: Entering directory '/home/pq/git/wayland/wayland-1.6.90/_build/doc/publican'
  GEN      en-US/ClientAPI.xml.tmp
/bin/sh: en-US/ClientAPI.xml.tmp: No such file or directory
Makefile:535: recipe for target 'en-US/ClientAPI.xml.tmp' failed
make[4]: *** [en-US/ClientAPI.xml.tmp] Error 1
make[4]: Leaving directory '/home/pq/git/wayland/wayland-1.6.90/_build/doc/publican'


Thanks,
pq