[PATCH 4/4] doc: Make it easier to add a new doxygen page
Bill Spitzak
spitzak at gmail.com
Fri Dec 5 19:04:08 PST 2014
If you have a library called Foo, you only have to add en-US/FooAPI.xml
to $publican_sources in publican/Makefile.am, and a list of C source
files to doxygen/Makefile.am.
---
doc/doxygen/Makefile.am | 29 +++++++++--------------------
doc/publican/Makefile.am | 26 +++++++++-----------------
doc/publican/doxygen-to-publican.xsl | 5 ++---
doc/publican/sources/Wayland.xml | 4 ++--
4 files changed, 22 insertions(+), 42 deletions(-)
diff --git a/doc/doxygen/Makefile.am b/doc/doxygen/Makefile.am
index 6c87743..dd74fc8 100644
--- a/doc/doxygen/Makefile.am
+++ b/doc/doxygen/Makefile.am
@@ -1,49 +1,38 @@
-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_shared) \
+ $(scanned_src_files_Server) \
$(top_srcdir)/src/wayland-client.c \
- $(top_srcdir)/src/wayland-client.h \
- $(top_srcdir)/src/wayland-server.c \
- $(top_srcdir)/src/wayland-server.h \
- $(top_srcdir)/src/wayland-shm.c
+ $(top_srcdir)/src/wayland-client.h
# find all man/man3/wl_foo.3 pages
# for this to work, we need to create them before the man target (hence
# all-local below)
dist_man3_MANS = $(shell test -d man && find man/man3 -name "wl_*.3" -printf "man/man3/%P\n")
-xml/client/index.xml: $(scanned_src_files_client) wayland.doxygen
- $(AM_V_GEN)$(MKDIR_P) xml/client && \
- (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
- $(AM_V_GEN)$(MKDIR_P) xml/server && \
+xml/%/index.xml: $(scanned_src_files_%) wayland.doxygen
+ $(AM_V_GEN)$(MKDIR_P) xml/$* && \
(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
diff --git a/doc/publican/Makefile.am b/doc/publican/Makefile.am
index d4514cc..35b9955 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
publican_sources = \
@@ -31,8 +29,8 @@ publican_sources = \
$(srcdir)/sources/images/x-architecture.png \
en-US/ProtocolSpec.xml \
en-US/ProtocolInterfaces.xml \
- en-US/WaylandClientAPI.xml \
- en-US/WaylandServerAPI.xml
+ en-US/ClientAPI.xml \
+ en-US/ServerAPI.xml
css_sources = \
$(srcdir)/sources/css/brand.css \
@@ -85,23 +83,17 @@ en-US/ProtocolInterfaces.xml: $(top_srcdir)/protocol/wayland.xml $(srcdir)/proto
# * use doxygen's combine.xslt to merge the xml files into one single file
# * move wayland-<foo>_8h.xml back to its original location
en-US/%API.xml.tmp: $(top_builddir)/doc/doxygen/xml/%/index.xml
- $(AM_V_GEN)mv $(top_builddir)/doc/doxygen/xml/$*/wayland-$*_8h.xml \
+ $(AM_V_GEN)mv $(top_builddir)/doc/doxygen/xml/$*/wayland-*_8h.xml \
$(top_builddir)/doc/doxygen/xml/
$(AM_V_GEN)$(XSLTPROC) $(top_builddir)/doc/doxygen/xml/$*/combine.xslt \
$(top_builddir)/doc/doxygen/xml/$*/index.xml > $@
- $(AM_V_GEN)mv $(top_builddir)/doc/doxygen/xml/wayland-$*_8h.xml \
+ $(AM_V_GEN)mv $(top_builddir)/doc/doxygen/xml/wayland-*_8h.xml \
$(top_builddir)/doc/doxygen/xml/$*
-# WaylandClientAPI.xml:
-# merge doxygen xml files into one single file, then transform the combined XML file into docbook format
-en-US/WaylandClientAPI.xml: en-US/clientAPI.xml.tmp $(srcdir)/doxygen-to-publican.xsl
- $(AM_V_GEN)$(XSLTPROC) --stringparam which Client $(srcdir)/doxygen-to-publican.xsl \
- $(builddir)/en-US/clientAPI.xml.tmp > en-US/WaylandClientAPI.xml
-
-# WaylandServerAPI.xml: see WaylandClientAPI.xml
-en-US/WaylandServerAPI.xml: en-US/serverAPI.xml.tmp $(srcdir)/doxygen-to-publican.xsl
- $(AM_V_GEN)$(XSLTPROC) --stringparam which Server $(srcdir)/doxygen-to-publican.xsl \
- $(builddir)/en-US/serverAPI.xml.tmp > en-US/WaylandServerAPI.xml
+en-US/%API.xml: $(srcdir)/doxygen-to-publican.xsl en-US/%API.xml.tmp
+ $(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
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>
--
1.7.9.5
More information about the wayland-devel
mailing list