mirrors/wayland
1
0
Fork 0
mirror of https://gitlab.freedesktop.org/wayland/wayland.git synced 2025-10-31 22:25:25 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions
wayland/doc/doxygen/Makefile.am

105 lines
3.2 KiB
Text
Raw Normal View History

doc: Add auto-generated Wayland Library chapter For now only Wayland Client API is described on that chapter, which is extracted via doxygen on ./src/wayland-client.h. We apply a stylesheet (doxygen-to-publican) on doxygen output so it becomes docbook valid. Now all we need to do is populate that header while developing in order to grow a decent documentation. So please use it! Signed-off-by: Tiago Vignatti <tiago.vignatti@intel.com>
2012-10-11 17:42:09 +03:00
doc: Create hot-linked areas in documents. Added xslt processing to give DocBook output diagram image maps/hot-linked areas consistent with those automatically generated by Doxygen. Signed-off-by: Jon A. Cruz <jonc@osg.samsung.com>
2015-01-28 17:24:05 -08:00
.SUFFIXES = .gv .png .map
doc: Switch from static image files to generated diagrams. Switches diagrams from using static PNG images to instead generate them via simple graphviz DOT markup files. Signed-off-by: Jon A. Cruz <jonc@osg.samsung.com>
2015-01-28 17:24:04 -08:00
doc: generate doxygen html output from the scanner This switches the scanner to generate doxygen-compatible tags for the generated protocol headers, and hooks up the doxygen build to generate server and client-side API documentation. That documentation is now in Client/ and Server/, respectively. GENERATE_HTML is on by default and must be disabled for the xml/man targets to avoid messing up the new documentation. We disable all three three targets in the doxyfile (xml and man default to NO anyway) to make it obvious that they need to be set in the per-target instructions. Each protocol is a separate doxygen @page, with each interface a @subpage. Wayland only has one protocol, wayland-protocols will have these nested. Each protocol page has a list of interfaces and the copyright and description where available. All interfaces are grouped by doxygen @defgroup and @ingroups and appear in "Modules" in the generated output. Each interface subpage has the description and a link to the actual API doc. Function, struct and #defines are documented in doxygen style and associated with the matching interface. Note that pages and groups have fixed HTML file names and are directly linkable/bookmark-able. The @mainpage is a separate file that's included at build time. It doesn't contain much other than links to where the interesting bits are. It's a static file though that supports markdown, so we can extend it easily in the future. For doxygen we need the new options EXTRACT_ALL and OPTIMIZE_OUTPUT_FOR_C so it scans C code properly. EXTRACT_STATIC is needed since most of the protocol hooks are static. Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net> Reviewed-by: Bryce Harrington <bryce@osg.samsung.com>
2016-03-01 09:26:21 +10:00
noinst_DATA = \
xml/Client/index.xml \
xml/Server/index.xml \
html/Client/index.html \
html/Server/index.html
doc: Add auto-generated Wayland Library chapter For now only Wayland Client API is described on that chapter, which is extracted via doxygen on ./src/wayland-client.h. We apply a stylesheet (doxygen-to-publican) on doxygen output so it becomes docbook valid. Now all we need to do is populate that header while developing in order to grow a decent documentation. So please use it! Signed-off-by: Tiago Vignatti <tiago.vignatti@intel.com>
2012-10-11 17:42:09 +03:00
dist_noinst_DATA = wayland.doxygen.in
doc: Include wayland-util.* for doxygen output This commit creates a shared file list that is included by both the client and the server for the XML Makefile targets, as classes within util are used by both the client and the server.
2013-09-15 13:37:09 -05:00
scanned_src_files_shared = \
$(top_srcdir)/src/wayland-util.h
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 <bryce@osg.samsung.com>
2014-12-16 19:23:03 -08:00
scanned_src_files_Client = \
doc: Include wayland-util.* for doxygen output This commit creates a shared file list that is included by both the client and the server for the XML Makefile targets, as classes within util are used by both the client and the server.
2013-09-15 13:37:09 -05:00
$(scanned_src_files_shared) \
doc: Update doxygen documentation when source files are changed
2012-10-19 15:30:26 +03:00
$(top_srcdir)/src/wayland-client.c \
introduce new headers wayland-client-core.h and wayland-server-core.h wayland-client.h and wayland-server.h include the protocol headers generated at build time. This means that a libwayland user cannot generate and use protocol code created from a wayland.xml newer than the installed libwayland, because it is not possible to only include the API header. Another use case is language bindings, which would generate their own protocol code and which only need to use the library ABI, not the generated C code. This commit adds wayland-client-core.h and wayland-server-core.h which do not include the protocol headers or any deprecated code. Reviewed-by: Jason Ekstrand <jason@jlekstrand.net> Reviewed-by: Pekka Paalanen <pekka.paalanen@collabora.co.uk>
2015-04-29 16:34:47 +03:00
$(top_srcdir)/src/wayland-client.h \
$(top_srcdir)/src/wayland-client-core.h
doc: Update doxygen documentation when source files are changed
2012-10-19 15:30:26 +03:00
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 <bryce@osg.samsung.com>
2014-12-16 19:23:03 -08:00
scanned_src_files_Server = \
doc: Include wayland-util.* for doxygen output This commit creates a shared file list that is included by both the client and the server for the XML Makefile targets, as classes within util are used by both the client and the server.
2013-09-15 13:37:09 -05:00
$(scanned_src_files_shared) \
server: document wl_event_loop and wl_event_source This documents all the public API related to wl_event_loop and wl_event_source objects. Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.co.uk> Reviewed-by: Yong Bakos <ybakos@humanoriented.com> [Pekka: fixed typos pointed by Yong] [Pekka: fixed typos pointed by Christopher] Reviewed-By: Christopher James Halse Rogers <christopher.halse.rogers@canonical.com>
2017-03-03 17:50:22 +02:00
$(top_srcdir)/src/event-loop.c \
doc: generate man pages from doxygen Create client-side and server-side man pages from doxygen. The doxygen config options are virtually the same as for the XML output, but we do pass in the specific options via stdin. WL_EXPORT is predefined to the empty string, it makes the man page look confusing and provides no value here anyway. This applies for both xml and man output. JAVADOC_AUTOBRIEF is disabled for man pages, the formatting in the resulting man page is IMO hard to read. Most of the server man pages are virtually empty, there's just not enough documentation in the source files. Interesting issue: the usage of @code in the protocol to reference the parameter breaks the expansion of WL_EXPORT, thus leaving us with WL_EXPORT in all the man pages. Presumably this is an issue with doxygen interpreting this as a @code command, but I already wasted enough time narrowing this down. Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
2013-04-02 11:08:59 +10:00
$(top_srcdir)/src/wayland-server.c \
Add documentation for wl_shm_buffer_begin/end_access It's not obvious that these functions are needed so it would be good to have some documentation for them.
2013-11-14 12:28:51 +00:00
$(top_srcdir)/src/wayland-server.h \
introduce new headers wayland-client-core.h and wayland-server-core.h wayland-client.h and wayland-server.h include the protocol headers generated at build time. This means that a libwayland user cannot generate and use protocol code created from a wayland.xml newer than the installed libwayland, because it is not possible to only include the API header. Another use case is language bindings, which would generate their own protocol code and which only need to use the library ABI, not the generated C code. This commit adds wayland-client-core.h and wayland-server-core.h which do not include the protocol headers or any deprecated code. Reviewed-by: Jason Ekstrand <jason@jlekstrand.net> Reviewed-by: Pekka Paalanen <pekka.paalanen@collabora.co.uk>
2015-04-29 16:34:47 +03:00
$(top_srcdir)/src/wayland-server-core.h \
Add documentation for wl_shm_buffer_begin/end_access It's not obvious that these functions are needed so it would be good to have some documentation for them.
2013-11-14 12:28:51 +00:00
$(top_srcdir)/src/wayland-shm.c
doc: generate man pages from doxygen Create client-side and server-side man pages from doxygen. The doxygen config options are virtually the same as for the XML output, but we do pass in the specific options via stdin. WL_EXPORT is predefined to the empty string, it makes the man page look confusing and provides no value here anyway. This applies for both xml and man output. JAVADOC_AUTOBRIEF is disabled for man pages, the formatting in the resulting man page is IMO hard to read. Most of the server man pages are virtually empty, there's just not enough documentation in the source files. Interesting issue: the usage of @code in the protocol to reference the parameter breaks the expansion of WL_EXPORT, thus leaving us with WL_EXPORT in all the man pages. Presumably this is an issue with doxygen interpreting this as a @code command, but I already wasted enough time narrowing this down. Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
2013-04-02 11:08:59 +10:00
doc: fix doxygen->man command line It was telling it to scan the doxyfile as well as the C source, and listing some source files more than once. Reviewed-by: Bryce Harrington <b.harrington@samsung.com> Reviewed-by: Pekka Paalanen <pekka.paalanen@collabora.co.uk>
2014-12-09 17:01:11 -08:00
scanned_src_files_man = \
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 <bryce@osg.samsung.com>
2014-12-16 19:23:03 -08:00
$(scanned_src_files_Server) \
doc: fix doxygen->man command line It was telling it to scan the doxyfile as well as the C source, and listing some source files more than once. Reviewed-by: Bryce Harrington <b.harrington@samsung.com> Reviewed-by: Pekka Paalanen <pekka.paalanen@collabora.co.uk>
2014-12-09 17:01:11 -08:00
$(top_srcdir)/src/wayland-client.c \
introduce new headers wayland-client-core.h and wayland-server-core.h wayland-client.h and wayland-server.h include the protocol headers generated at build time. This means that a libwayland user cannot generate and use protocol code created from a wayland.xml newer than the installed libwayland, because it is not possible to only include the API header. Another use case is language bindings, which would generate their own protocol code and which only need to use the library ABI, not the generated C code. This commit adds wayland-client-core.h and wayland-server-core.h which do not include the protocol headers or any deprecated code. Reviewed-by: Jason Ekstrand <jason@jlekstrand.net> Reviewed-by: Pekka Paalanen <pekka.paalanen@collabora.co.uk>
2015-04-29 16:34:47 +03:00
$(top_srcdir)/src/wayland-client.h \
$(top_srcdir)/src/wayland-client-core.h
doc: fix doxygen->man command line It was telling it to scan the doxyfile as well as the C source, and listing some source files more than once. Reviewed-by: Bryce Harrington <b.harrington@samsung.com> Reviewed-by: Pekka Paalanen <pekka.paalanen@collabora.co.uk>
2014-12-09 17:01:11 -08:00
doc: generate doxygen html output from the scanner This switches the scanner to generate doxygen-compatible tags for the generated protocol headers, and hooks up the doxygen build to generate server and client-side API documentation. That documentation is now in Client/ and Server/, respectively. GENERATE_HTML is on by default and must be disabled for the xml/man targets to avoid messing up the new documentation. We disable all three three targets in the doxyfile (xml and man default to NO anyway) to make it obvious that they need to be set in the per-target instructions. Each protocol is a separate doxygen @page, with each interface a @subpage. Wayland only has one protocol, wayland-protocols will have these nested. Each protocol page has a list of interfaces and the copyright and description where available. All interfaces are grouped by doxygen @defgroup and @ingroups and appear in "Modules" in the generated output. Each interface subpage has the description and a link to the actual API doc. Function, struct and #defines are documented in doxygen style and associated with the matching interface. Note that pages and groups have fixed HTML file names and are directly linkable/bookmark-able. The @mainpage is a separate file that's included at build time. It doesn't contain much other than links to where the interesting bits are. It's a static file though that supports markdown, so we can extend it easily in the future. For doxygen we need the new options EXTRACT_ALL and OPTIMIZE_OUTPUT_FOR_C so it scans C code properly. EXTRACT_STATIC is needed since most of the protocol hooks are static. Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net> Reviewed-by: Bryce Harrington <bryce@osg.samsung.com>
2016-03-01 09:26:21 +10:00
extra_doxygen = \
mainpage.dox
extra_doxygen_Server = \
$(top_builddir)/protocol/wayland-server-protocol.h \
$(extra_doxygen)
extra_doxygen_Client = \
$(top_builddir)/protocol/wayland-client-protocol.h \
$(extra_doxygen)
doc: Fix out-of-tree build and also distcheck Corrects an issue that would cause out-of-tree builds to fail and also a few items that would cause distcheck to fail. Signed-off-by: Jon A. Cruz <jonc@osg.samsung.com> Reviewed-by: Bryce Harrington <bryce@osg.samsung.com>
2015-01-30 18:07:24 -08:00
diagramsdir := $(srcdir)/dot
doc: Switch from static image files to generated diagrams. Switches diagrams from using static PNG images to instead generate them via simple graphviz DOT markup files. Signed-off-by: Jon A. Cruz <jonc@osg.samsung.com>
2015-01-28 17:24:04 -08:00
diagramssrc := $(wildcard $(diagramsdir)/*.gv)
diagrams := $(patsubst $(diagramsdir)/%,xml/%,$(diagramssrc:.gv=.png))
doc: Create hot-linked areas in documents. Added xslt processing to give DocBook output diagram image maps/hot-linked areas consistent with those automatically generated by Doxygen. Signed-off-by: Jon A. Cruz <jonc@osg.samsung.com>
2015-01-28 17:24:05 -08:00
diagram_maps := $(patsubst $(diagramsdir)/%,xml/%,$(diagramssrc:.gv=.map))
doc: Switch from static image files to generated diagrams. Switches diagrams from using static PNG images to instead generate them via simple graphviz DOT markup files. Signed-off-by: Jon A. Cruz <jonc@osg.samsung.com>
2015-01-28 17:24:04 -08:00
doc: use a dynamic list of man pages This requires that doxygen is run before the man target so find can actually find the man pages. Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
2013-04-04 11:29:01 +10:00
# 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)
doc: Quell warnings about missing man3 directory before its been built The shell command for dist_man3_MANS gets invoked several times during the make process but before the man pages have been generated, which causes the following warnings when running `make`: find: `man/man3': No such file or directory find: `man/man3': No such file or directory find: `man/man3': No such file or directory GEN xml/client/index.xml Despite these error messages, the generated dist tarball contains the man3 pages as intended, both before and after this patch. $ make dist $ tar xxf wayland-1.5.90.tar.xz $ find wayland-1.5.90/doc/doxygen/man/man3 -name "wl_*.3" | wc -l 85 Signed-off-by: Bryce Harrington <b.harrington@samsung.com> Acked-by: Peter Hutterer <peter.hutterer@who-t.net> Tested-by: Pekka Paalanen <pekka.paalanen@collabora.co.uk>
2014-07-21 19:23:49 +00:00
dist_man3_MANS = $(shell test -d man && find man/man3 -name "wl_*.3" -printf "man/man3/%P\n")
doc: generate man pages from doxygen Create client-side and server-side man pages from doxygen. The doxygen config options are virtually the same as for the XML output, but we do pass in the specific options via stdin. WL_EXPORT is predefined to the empty string, it makes the man page look confusing and provides no value here anyway. This applies for both xml and man output. JAVADOC_AUTOBRIEF is disabled for man pages, the formatting in the resulting man page is IMO hard to read. Most of the server man pages are virtually empty, there's just not enough documentation in the source files. Interesting issue: the usage of @code in the protocol to reference the parameter breaks the expansion of WL_EXPORT, thus leaving us with WL_EXPORT in all the man pages. Presumably this is an issue with doxygen interpreting this as a @code command, but I already wasted enough time narrowing this down. Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
2013-04-02 11:08:59 +10:00
doc: Minor makefile cleanup. Split out directory creation to leverage order only prerequisites. Signed-off-by: Jon A. Cruz <jonc@osg.samsung.com> Acked-by: Peter Hutterer <peter.hutterer@who-t.net> Acked-by: Pekka Paalanen <pekka.paalanen@collabora.co.uk>
2014-12-09 01:34:23 -08:00
# Listing various directories that might need to be created.
build/doc: Ensure destination dir exists despite VPATH Make considers a variable called VPATH when trying to satisfy dependencies, e.g. for a target 'foo', it will consider the target extant if VPATH is '../../bar' and '../../bar/foo' exists. Part of the doc build, the '$(alldirs)' target, exists to create the target directories if they do not exist. For example, before generating xml/wayland-architecture.png, it will ensure the 'xml' target is considered up-to-date thanks to the target dependency. Creating $(srcdir)/doc/doxygen/xml thus means that the 'xml' dependency will be satisfied, so we'll never create the output directory, and the doc build will fail. Change the alldirs target list to be absolute paths, so VPATH will not be consulted and defeat the entire point of what we're trying to do. This fixes the Meson build, where we later create doc/doxygen/xml/meson.build. Signed-off-by: Daniel Stone <daniels@collabora.com> Reviewed-by: Pekka Paalanen <pekka.paalanen@collabora.com>
2018-07-22 10:00:26 +01:00
alldirsrel := xml xml/Client xml/Server man/man3 html/Client html/Server
alldirs := $(patsubst %,$(CURDIR)/%,$(alldirsrel))
doc: Minor makefile cleanup. Split out directory creation to leverage order only prerequisites. Signed-off-by: Jon A. Cruz <jonc@osg.samsung.com> Acked-by: Peter Hutterer <peter.hutterer@who-t.net> Acked-by: Pekka Paalanen <pekka.paalanen@collabora.co.uk>
2014-12-09 01:34:23 -08:00
doc: Switch from static image files to generated diagrams. Switches diagrams from using static PNG images to instead generate them via simple graphviz DOT markup files. Signed-off-by: Jon A. Cruz <jonc@osg.samsung.com>
2015-01-28 17:24:04 -08:00
$(diagrams): $(diagramssrc)
doc: Create hot-linked areas in documents. Added xslt processing to give DocBook output diagram image maps/hot-linked areas consistent with those automatically generated by Doxygen. Signed-off-by: Jon A. Cruz <jonc@osg.samsung.com>
2015-01-28 17:24:05 -08:00
$(diagram_maps): $(diagramssrc)
build/doc: Ensure destination dir exists despite VPATH Make considers a variable called VPATH when trying to satisfy dependencies, e.g. for a target 'foo', it will consider the target extant if VPATH is '../../bar' and '../../bar/foo' exists. Part of the doc build, the '$(alldirs)' target, exists to create the target directories if they do not exist. For example, before generating xml/wayland-architecture.png, it will ensure the 'xml' target is considered up-to-date thanks to the target dependency. Creating $(srcdir)/doc/doxygen/xml thus means that the 'xml' dependency will be satisfied, so we'll never create the output directory, and the doc build will fail. Change the alldirs target list to be absolute paths, so VPATH will not be consulted and defeat the entire point of what we're trying to do. This fixes the Meson build, where we later create doc/doxygen/xml/meson.build. Signed-off-by: Daniel Stone <daniels@collabora.com> Reviewed-by: Pekka Paalanen <pekka.paalanen@collabora.com>
2018-07-22 10:00:26 +01:00
xml/%/index.xml: $(top_srcdir)/src/scanner.c $(scanned_src_files_%) wayland.doxygen $(diagrams) $(diagram_maps) | $(CURDIR)/xml/%
doc: Minor makefile cleanup. Split out directory creation to leverage order only prerequisites. Signed-off-by: Jon A. Cruz <jonc@osg.samsung.com> Acked-by: Peter Hutterer <peter.hutterer@who-t.net> Acked-by: Pekka Paalanen <pekka.paalanen@collabora.co.uk>
2014-12-09 01:34:23 -08:00
$(AM_V_GEN)(cat wayland.doxygen; \
doc: generate server documentation from XML too Same as WaylandClientAPI.xml we now also generate WaylandServerAPI.xml for publication. Most of this hunk is just adding a client/ or server/ into the xml path to keep the two separate. The change in wayland.doxygen now causes a standard doxygen call to not generate anything - what is generated is specified through the options passed by make. Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
2013-04-04 11:28:58 +10:00
echo "GENERATE_XML=YES"; \
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 <bryce@osg.samsung.com>
2014-12-16 19:23:03 -08:00
echo "XML_OUTPUT=xml/$*"; \
echo "INPUT= $(scanned_src_files_$*)"; \
doc: Invoke doxygen via the defined make variable. Invoke doxygen via the autoconf-defined make variable instead of directly. This brings it in line with standard makefile practices. Signed-off-by: Jon A. Cruz <jonc@osg.samsung.com> Reviewed-by: Peter Hutterer <peter.hutterer@who-t.net>
2014-12-02 17:54:07 -08:00
) | $(DOXYGEN) -
doc: Add auto-generated Wayland Library chapter For now only Wayland Client API is described on that chapter, which is extracted via doxygen on ./src/wayland-client.h. We apply a stylesheet (doxygen-to-publican) on doxygen output so it becomes docbook valid. Now all we need to do is populate that header while developing in order to grow a decent documentation. So please use it! Signed-off-by: Tiago Vignatti <tiago.vignatti@intel.com>
2012-10-11 17:42:09 +03:00
build/doc: Ensure destination dir exists despite VPATH Make considers a variable called VPATH when trying to satisfy dependencies, e.g. for a target 'foo', it will consider the target extant if VPATH is '../../bar' and '../../bar/foo' exists. Part of the doc build, the '$(alldirs)' target, exists to create the target directories if they do not exist. For example, before generating xml/wayland-architecture.png, it will ensure the 'xml' target is considered up-to-date thanks to the target dependency. Creating $(srcdir)/doc/doxygen/xml thus means that the 'xml' dependency will be satisfied, so we'll never create the output directory, and the doc build will fail. Change the alldirs target list to be absolute paths, so VPATH will not be consulted and defeat the entire point of what we're trying to do. This fixes the Meson build, where we later create doc/doxygen/xml/meson.build. Signed-off-by: Daniel Stone <daniels@collabora.com> Reviewed-by: Pekka Paalanen <pekka.paalanen@collabora.com>
2018-07-22 10:00:26 +01:00
html/%/index.html: $(scanned_src_files_%) wayland.doxygen $(diagrams) $(diagram_maps) | $(CURDIR)/html/%
doc: generate doxygen html output from the scanner This switches the scanner to generate doxygen-compatible tags for the generated protocol headers, and hooks up the doxygen build to generate server and client-side API documentation. That documentation is now in Client/ and Server/, respectively. GENERATE_HTML is on by default and must be disabled for the xml/man targets to avoid messing up the new documentation. We disable all three three targets in the doxyfile (xml and man default to NO anyway) to make it obvious that they need to be set in the per-target instructions. Each protocol is a separate doxygen @page, with each interface a @subpage. Wayland only has one protocol, wayland-protocols will have these nested. Each protocol page has a list of interfaces and the copyright and description where available. All interfaces are grouped by doxygen @defgroup and @ingroups and appear in "Modules" in the generated output. Each interface subpage has the description and a link to the actual API doc. Function, struct and #defines are documented in doxygen style and associated with the matching interface. Note that pages and groups have fixed HTML file names and are directly linkable/bookmark-able. The @mainpage is a separate file that's included at build time. It doesn't contain much other than links to where the interesting bits are. It's a static file though that supports markdown, so we can extend it easily in the future. For doxygen we need the new options EXTRACT_ALL and OPTIMIZE_OUTPUT_FOR_C so it scans C code properly. EXTRACT_STATIC is needed since most of the protocol hooks are static. Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net> Reviewed-by: Bryce Harrington <bryce@osg.samsung.com>
2016-03-01 09:26:21 +10:00
$(AM_V_GEN)(cat wayland.doxygen; \
doc: link between client and server doc and to the wayland book And insert "client" or "server" into the PROJECT_NAME to know which one we have. Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net> Reviewed-by: Bryce Harrington <bryce@osg.samsung.com>
2016-03-01 09:28:49 +10:00
echo "PROJECT_NAME=\"Wayland $* API\""; \
doc: generate doxygen html output from the scanner This switches the scanner to generate doxygen-compatible tags for the generated protocol headers, and hooks up the doxygen build to generate server and client-side API documentation. That documentation is now in Client/ and Server/, respectively. GENERATE_HTML is on by default and must be disabled for the xml/man targets to avoid messing up the new documentation. We disable all three three targets in the doxyfile (xml and man default to NO anyway) to make it obvious that they need to be set in the per-target instructions. Each protocol is a separate doxygen @page, with each interface a @subpage. Wayland only has one protocol, wayland-protocols will have these nested. Each protocol page has a list of interfaces and the copyright and description where available. All interfaces are grouped by doxygen @defgroup and @ingroups and appear in "Modules" in the generated output. Each interface subpage has the description and a link to the actual API doc. Function, struct and #defines are documented in doxygen style and associated with the matching interface. Note that pages and groups have fixed HTML file names and are directly linkable/bookmark-able. The @mainpage is a separate file that's included at build time. It doesn't contain much other than links to where the interesting bits are. It's a static file though that supports markdown, so we can extend it easily in the future. For doxygen we need the new options EXTRACT_ALL and OPTIMIZE_OUTPUT_FOR_C so it scans C code properly. EXTRACT_STATIC is needed since most of the protocol hooks are static. Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net> Reviewed-by: Bryce Harrington <bryce@osg.samsung.com>
2016-03-01 09:26:21 +10:00
echo "GENERATE_HTML=YES"; \
echo "HTML_OUTPUT=html/$*"; \
echo "INPUT= $(scanned_src_files_$*) $(extra_doxygen_$*)"; \
) | $(DOXYGEN) -
build/doc: Ensure destination dir exists despite VPATH Make considers a variable called VPATH when trying to satisfy dependencies, e.g. for a target 'foo', it will consider the target extant if VPATH is '../../bar' and '../../bar/foo' exists. Part of the doc build, the '$(alldirs)' target, exists to create the target directories if they do not exist. For example, before generating xml/wayland-architecture.png, it will ensure the 'xml' target is considered up-to-date thanks to the target dependency. Creating $(srcdir)/doc/doxygen/xml thus means that the 'xml' dependency will be satisfied, so we'll never create the output directory, and the doc build will fail. Change the alldirs target list to be absolute paths, so VPATH will not be consulted and defeat the entire point of what we're trying to do. This fixes the Meson build, where we later create doc/doxygen/xml/meson.build. Signed-off-by: Daniel Stone <daniels@collabora.com> Reviewed-by: Pekka Paalanen <pekka.paalanen@collabora.com>
2018-07-22 10:00:26 +01:00
man/man3/wl_display.3: $(top_srcdir)/src/scanner.c $(scanned_src_files_man) wayland.doxygen | $(CURDIR)/man/man3
build: hide doxygen commands with AM_V_GEN I suppose the purpose was to print just one GEN line for each doxygen rule being executed, not print the doxygen command. Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.co.uk>
2014-03-10 14:03:59 +02:00
$(AM_V_GEN)(cat wayland.doxygen; \
doc: generate man pages from doxygen Create client-side and server-side man pages from doxygen. The doxygen config options are virtually the same as for the XML output, but we do pass in the specific options via stdin. WL_EXPORT is predefined to the empty string, it makes the man page look confusing and provides no value here anyway. This applies for both xml and man output. JAVADOC_AUTOBRIEF is disabled for man pages, the formatting in the resulting man page is IMO hard to read. Most of the server man pages are virtually empty, there's just not enough documentation in the source files. Interesting issue: the usage of @code in the protocol to reference the parameter breaks the expansion of WL_EXPORT, thus leaving us with WL_EXPORT in all the man pages. Presumably this is an issue with doxygen interpreting this as a @code command, but I already wasted enough time narrowing this down. Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
2013-04-02 11:08:59 +10:00
echo "GENERATE_MAN=YES"; \
echo "MAN_OUTPUT=man"; \
echo "JAVADOC_AUTOBRIEF=NO"; \
doc: fix doxygen->man command line It was telling it to scan the doxyfile as well as the C source, and listing some source files more than once. Reviewed-by: Bryce Harrington <b.harrington@samsung.com> Reviewed-by: Pekka Paalanen <pekka.paalanen@collabora.co.uk>
2014-12-09 17:01:11 -08:00
echo "INPUT= $(scanned_src_files_man)"; \
doc: Invoke doxygen via the defined make variable. Invoke doxygen via the autoconf-defined make variable instead of directly. This brings it in line with standard makefile practices. Signed-off-by: Jon A. Cruz <jonc@osg.samsung.com> Reviewed-by: Peter Hutterer <peter.hutterer@who-t.net>
2014-12-02 17:54:07 -08:00
) | $(DOXYGEN) -
doc: generate man pages from doxygen Create client-side and server-side man pages from doxygen. The doxygen config options are virtually the same as for the XML output, but we do pass in the specific options via stdin. WL_EXPORT is predefined to the empty string, it makes the man page look confusing and provides no value here anyway. This applies for both xml and man output. JAVADOC_AUTOBRIEF is disabled for man pages, the formatting in the resulting man page is IMO hard to read. Most of the server man pages are virtually empty, there's just not enough documentation in the source files. Interesting issue: the usage of @code in the protocol to reference the parameter breaks the expansion of WL_EXPORT, thus leaving us with WL_EXPORT in all the man pages. Presumably this is an issue with doxygen interpreting this as a @code command, but I already wasted enough time narrowing this down. Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
2013-04-02 11:08:59 +10:00
build/doc: Ensure destination dir exists despite VPATH Make considers a variable called VPATH when trying to satisfy dependencies, e.g. for a target 'foo', it will consider the target extant if VPATH is '../../bar' and '../../bar/foo' exists. Part of the doc build, the '$(alldirs)' target, exists to create the target directories if they do not exist. For example, before generating xml/wayland-architecture.png, it will ensure the 'xml' target is considered up-to-date thanks to the target dependency. Creating $(srcdir)/doc/doxygen/xml thus means that the 'xml' dependency will be satisfied, so we'll never create the output directory, and the doc build will fail. Change the alldirs target list to be absolute paths, so VPATH will not be consulted and defeat the entire point of what we're trying to do. This fixes the Meson build, where we later create doc/doxygen/xml/meson.build. Signed-off-by: Daniel Stone <daniels@collabora.com> Reviewed-by: Pekka Paalanen <pekka.paalanen@collabora.com>
2018-07-22 10:00:26 +01:00
xml/%.png: $(diagramsdir)/%.gv | $(CURDIR)/xml
doc: Switch from static image files to generated diagrams. Switches diagrams from using static PNG images to instead generate them via simple graphviz DOT markup files. Signed-off-by: Jon A. Cruz <jonc@osg.samsung.com>
2015-01-28 17:24:04 -08:00
$(AM_V_GEN)$(DOT) -Tpng -o$@ $<
build/doc: Ensure destination dir exists despite VPATH Make considers a variable called VPATH when trying to satisfy dependencies, e.g. for a target 'foo', it will consider the target extant if VPATH is '../../bar' and '../../bar/foo' exists. Part of the doc build, the '$(alldirs)' target, exists to create the target directories if they do not exist. For example, before generating xml/wayland-architecture.png, it will ensure the 'xml' target is considered up-to-date thanks to the target dependency. Creating $(srcdir)/doc/doxygen/xml thus means that the 'xml' dependency will be satisfied, so we'll never create the output directory, and the doc build will fail. Change the alldirs target list to be absolute paths, so VPATH will not be consulted and defeat the entire point of what we're trying to do. This fixes the Meson build, where we later create doc/doxygen/xml/meson.build. Signed-off-by: Daniel Stone <daniels@collabora.com> Reviewed-by: Pekka Paalanen <pekka.paalanen@collabora.com>
2018-07-22 10:00:26 +01:00
xml/%.map: $(diagramsdir)/%.gv | $(CURDIR)/xml
doc: Create hot-linked areas in documents. Added xslt processing to give DocBook output diagram image maps/hot-linked areas consistent with those automatically generated by Doxygen. Signed-off-by: Jon A. Cruz <jonc@osg.samsung.com>
2015-01-28 17:24:05 -08:00
$(AM_V_GEN)$(DOT) -Tcmapx_np -o$@ $<
doc: Minor makefile cleanup. Split out directory creation to leverage order only prerequisites. Signed-off-by: Jon A. Cruz <jonc@osg.samsung.com> Acked-by: Peter Hutterer <peter.hutterer@who-t.net> Acked-by: Pekka Paalanen <pekka.paalanen@collabora.co.uk>
2014-12-09 01:34:23 -08:00
# general rule to create one of the listed directories.
$(alldirs):
$(AM_V_GEN)$(MKDIR_P) $@
doc: use a dynamic list of man pages This requires that doxygen is run before the man target so find can actually find the man pages. Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
2013-04-04 11:29:01 +10:00
# there is no man-local
doc: do not rebuild man pages if they are up to date The doxygen.man make target was not a real file that was generated, therefore the man page rule was ran on every make invocation. Replace it with a real file that is produced by the man page rule. Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.co.uk>
2014-03-10 14:03:58 +02:00
all-local: man/man3/wl_display.3
doc: generate man pages from doxygen Create client-side and server-side man pages from doxygen. The doxygen config options are virtually the same as for the XML output, but we do pass in the specific options via stdin. WL_EXPORT is predefined to the empty string, it makes the man page look confusing and provides no value here anyway. This applies for both xml and man output. JAVADOC_AUTOBRIEF is disabled for man pages, the formatting in the resulting man page is IMO hard to read. Most of the server man pages are virtually empty, there's just not enough documentation in the source files. Interesting issue: the usage of @code in the protocol to reference the parameter breaks the expansion of WL_EXPORT, thus leaving us with WL_EXPORT in all the man pages. Presumably this is an issue with doxygen interpreting this as a @code command, but I already wasted enough time narrowing this down. Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
2013-04-02 11:08:59 +10:00
doc: Add auto-generated Wayland Library chapter For now only Wayland Client API is described on that chapter, which is extracted via doxygen on ./src/wayland-client.h. We apply a stylesheet (doxygen-to-publican) on doxygen output so it becomes docbook valid. Now all we need to do is populate that header while developing in order to grow a decent documentation. So please use it! Signed-off-by: Tiago Vignatti <tiago.vignatti@intel.com>
2012-10-11 17:42:09 +03:00
clean-local:
rm -rf xml/
doc: generate doxygen html output from the scanner This switches the scanner to generate doxygen-compatible tags for the generated protocol headers, and hooks up the doxygen build to generate server and client-side API documentation. That documentation is now in Client/ and Server/, respectively. GENERATE_HTML is on by default and must be disabled for the xml/man targets to avoid messing up the new documentation. We disable all three three targets in the doxyfile (xml and man default to NO anyway) to make it obvious that they need to be set in the per-target instructions. Each protocol is a separate doxygen @page, with each interface a @subpage. Wayland only has one protocol, wayland-protocols will have these nested. Each protocol page has a list of interfaces and the copyright and description where available. All interfaces are grouped by doxygen @defgroup and @ingroups and appear in "Modules" in the generated output. Each interface subpage has the description and a link to the actual API doc. Function, struct and #defines are documented in doxygen style and associated with the matching interface. Note that pages and groups have fixed HTML file names and are directly linkable/bookmark-able. The @mainpage is a separate file that's included at build time. It doesn't contain much other than links to where the interesting bits are. It's a static file though that supports markdown, so we can extend it easily in the future. For doxygen we need the new options EXTRACT_ALL and OPTIMIZE_OUTPUT_FOR_C so it scans C code properly. EXTRACT_STATIC is needed since most of the protocol hooks are static. Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net> Reviewed-by: Bryce Harrington <bryce@osg.samsung.com>
2016-03-01 09:26:21 +10:00
rm -rf html/
doc: generate man pages from doxygen Create client-side and server-side man pages from doxygen. The doxygen config options are virtually the same as for the XML output, but we do pass in the specific options via stdin. WL_EXPORT is predefined to the empty string, it makes the man page look confusing and provides no value here anyway. This applies for both xml and man output. JAVADOC_AUTOBRIEF is disabled for man pages, the formatting in the resulting man page is IMO hard to read. Most of the server man pages are virtually empty, there's just not enough documentation in the source files. Interesting issue: the usage of @code in the protocol to reference the parameter breaks the expansion of WL_EXPORT, thus leaving us with WL_EXPORT in all the man pages. Presumably this is an issue with doxygen interpreting this as a @code command, but I already wasted enough time narrowing this down. Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
2013-04-02 11:08:59 +10:00
rm -rf man/
doc: Fix out-of-tree build and also distcheck Corrects an issue that would cause out-of-tree builds to fail and also a few items that would cause distcheck to fail. Signed-off-by: Jon A. Cruz <jonc@osg.samsung.com> Reviewed-by: Bryce Harrington <bryce@osg.samsung.com>
2015-01-30 18:07:24 -08:00
EXTRA_DIST = $(diagramssrc)
Reference in a new issue Copy permalink