mirrors/wayland
1
0
Fork 0
mirror of https://gitlab.freedesktop.org/wayland/wayland.git synced 2026-04-04 07:15:53 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions

doc: Make it easier to add a new doxygen page

Browse source 
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 <bryce@osg.samsung.com>
This commit is contained in:
Bill Spitzak 2014-12-16 19:23:03 -08:00 • committed by Pekka Paalanen
parent 3f05c4ac4a
commit 6e3ad249ad
4 changed files with 25 additions and 41 deletions
Download patch file Download diff file Expand all files Collapse all files

23
doc/doxygen/Makefile.am
View file

@ -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 dist_noinst_DATA = wayland.doxygen.in
scanned_src_files_shared = \ scanned_src_files_shared = \
$(top_srcdir)/src/wayland-util.c \ $(top_srcdir)/src/wayland-util.c \
$(top_srcdir)/src/wayland-util.h $(top_srcdir)/src/wayland-util.h
scanned_src_files_client = \ scanned_src_files_Client = \
$(scanned_src_files_shared) \ $(scanned_src_files_shared) \
$(top_srcdir)/src/wayland-client.c \ $(top_srcdir)/src/wayland-client.c \
$(top_srcdir)/src/wayland-client.h $(top_srcdir)/src/wayland-client.h
scanned_src_files_server = \ scanned_src_files_Server = \
$(scanned_src_files_shared) \ $(scanned_src_files_shared) \
$(top_srcdir)/src/wayland-server.c \ $(top_srcdir)/src/wayland-server.c \
$(top_srcdir)/src/wayland-server.h \ $(top_srcdir)/src/wayland-server.h \
$(top_srcdir)/src/wayland-shm.c $(top_srcdir)/src/wayland-shm.c
scanned_src_files_man = \ scanned_src_files_man = \
$(scanned_src_files_server) \ $(scanned_src_files_Server) \
$(top_srcdir)/src/wayland-client.c \ $(top_srcdir)/src/wayland-client.c \
$(top_srcdir)/src/wayland-client.h $(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") 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. # 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; \ $(AM_V_GEN)(cat wayland.doxygen; \
echo "GENERATE_XML=YES"; \ echo "GENERATE_XML=YES"; \
echo "XML_OUTPUT=xml/client"; \ echo "XML_OUTPUT=xml/$*"; \
echo "INPUT= $(scanned_src_files_client)"; \ echo "INPUT= $(scanned_src_files_$*)"; \
) | $(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)"; \
) | $(DOXYGEN) - ) | $(DOXYGEN) -
man/man3/wl_display.3: $(scanned_src_files_man) wayland.doxygen | man/man3 man/man3/wl_display.3: $(scanned_src_files_man) wayland.doxygen | man/man3

34
doc/publican/Makefile.am
View file

@ -8,9 +8,7 @@
# * ProtocolSpec.xml is generated from $(top_srcdir)/protocol/wayland.xml, # * ProtocolSpec.xml is generated from $(top_srcdir)/protocol/wayland.xml,
# changed into docbook via XSLT and saved in $(builddir)/en-US/ # changed into docbook via XSLT and saved in $(builddir)/en-US/
# * ProtocolInterfaces.xml, same as above, uses a different XSLT # * ProtocolInterfaces.xml, same as above, uses a different XSLT
# * WaylandClientAPI.xml is generated from the doxygen output and saved in # * *API.xml is generated from the doxygen output and saved in
# $(builddir)/en-US
# * WaylandServerAPI.xml is generated from the doxygen output and saved in
# $(builddir)/en-US # $(builddir)/en-US
# * run xmlto on $(builddir)/en-US, output to $(builddir)/Wayland/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 pubdir = $(docdir)/Wayland/en-US
publican_targets = $(publican_sources:$(srcdir)/sources/%=$(builddir)/en-US/%) \ publican_targets = $(publican_sources:$(srcdir)/sources%=$(builddir)/en-US/%) \
$(builddir)/en-US/ProtocolSpec.xml $(builddir)/en-US/ProtocolInterfaces.xml \ $(builddir)/en-US/ProtocolSpec.xml \
$(builddir)/en-US/WaylandClientAPI.xml $(builddir)/en-US/WaylandServerAPI.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 # 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 $(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, # * we don't want wayland-{server|client}_8h.xml to avoid duplicating output methods,
# move it out of the way first. # move it out of the way first.
# * use doxygen's combine.xslt to merge the xml files into one single file # * use doxygen's combine.xslt to merge the xml files into one single file
# * pipe that through the doxygen-to-publican stylesheet
# * move wayland-<foo>_8h.xml back to its original location # * move wayland-<foo>_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)$(MKDIR_P) $(doxydir)/xml/$*/saved
$(AM_V_at)mv $(doxydir)/xml/$*/wayland-*_8h.xml \ $(AM_V_at)mv $(doxydir)/xml/$*/wayland-*_8h.xml \
$(doxydir)/xml/$*/saved $(doxydir)/xml/$*/saved
$(AM_V_GEN)$(XSLTPROC) $(doxydir)/xml/$*/combine.xslt \ $(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/* \ $(AM_V_at)mv $(doxydir)/xml/$*/saved/* \
$(doxydir)/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 > $@
# Copy the sources source files into en-US destination # Copy the sources source files into en-US destination
# This is required for out-of-source-tree build as publican does not allow us # This is required for out-of-source-tree build as publican does not allow us
# to specify the location of the source code. # 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_GEN)cp -f $< $@
$(AM_V_at)chmod a+w $@ $(AM_V_at)chmod a+w $@
@ -124,7 +116,7 @@ $(builddir)/en-US/%: $(srcdir)/sources/% $(builddir)/en-US/ProtocolSpec.xml $(bu
$(alldirs): $(alldirs):
$(AM_V_GEN)$(MKDIR_P) $@ $(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: clean-local:
$(AM_V_at)rm -fr $(builddir)/en-US $(AM_V_at)rm -fr $(builddir)/en-US

5
doc/publican/doxygen-to-publican.xsl
View file

@ -29,9 +29,8 @@
<para> <para>
Following is the Wayland library classes for the Following is the Wayland library classes for the
<xsl:value-of select="$which"/> <emphasis>libwayland-<xsl:value-of select="translate($which,
(<emphasis>libwayland-<xsl:value-of select="translate($which, 'SC', 'sc')"/></emphasis>. This appendix describes in detail
'SC', 'sc')"/></emphasis>). This appendix describes in detail
the library's methods and their helpers, aiming implementors who the library's methods and their helpers, aiming implementors who
are building a Wayland <xsl:value-of select="translate($which, are building a Wayland <xsl:value-of select="translate($which,
'SC', 'sc')"/>. 'SC', 'sc')"/>.

4
doc/publican/sources/Wayland.xml
View file

@ -12,7 +12,7 @@
<xi:include href="Architecture.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <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="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="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="ClientAPI.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="ServerAPI.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
</book> </book>