Commit bd707406 authored by Philip Withnall's avatar Philip Withnall Committed by Simon McVittie

doc: Add a guide to designing D-Bus APIs

This guide gives some pointers on how to write D-Bus APIs which are nice
to use.

It adds an optional dependency on Ducktype and yelp-build from
yelp-tools. These are used when available, but are not required unless
--enable-ducktype-docs is passed to configure. They are required for
uploading the docs, however.

Bug: https://bugs.freedesktop.org/show_bug.cgi?id=88994Reviewed-by: default avatarSimon McVittie <simon.mcvittie@collabora.co.uk>
parent 4453665b
......@@ -150,6 +150,10 @@ AC_ARG_ENABLE(asserts, AS_HELP_STRING([--enable-asserts],[include assertion chec
AC_ARG_ENABLE(checks, AS_HELP_STRING([--enable-checks],[include sanity checks on public API]),enable_checks=$enableval,enable_checks=yes)
AC_ARG_ENABLE(xml-docs, AS_HELP_STRING([--enable-xml-docs],[build XML documentation (requires xmlto)]),enable_xml_docs=$enableval,enable_xml_docs=auto)
AC_ARG_ENABLE(doxygen-docs, AS_HELP_STRING([--enable-doxygen-docs],[build DOXYGEN documentation (requires Doxygen)]),enable_doxygen_docs=$enableval,enable_doxygen_docs=auto)
AC_ARG_ENABLE([ducktype-docs],
AS_HELP_STRING([--enable-ducktype-docs],
[build Ducktype documentation (requires Ducktype)]),
[enable_ducktype_docs=$enableval], [enable_ducktype_docs=auto])
AC_ARG_ENABLE(abstract-sockets, AS_HELP_STRING([--enable-abstract-sockets],[use abstract socket namespace (linux only)]),enable_abstract_sockets=$enableval,enable_abstract_sockets=auto)
AC_ARG_ENABLE(selinux, AS_HELP_STRING([--enable-selinux],[build with SELinux support]),enable_selinux=$enableval,enable_selinux=auto)
AC_ARG_ENABLE(libaudit,AS_HELP_STRING([--enable-libaudit],[build audit daemon support for SELinux]),enable_libaudit=$enableval,enable_libaudit=auto)
......@@ -1421,6 +1425,36 @@ AC_MSG_RESULT($enable_doxygen_docs)
AC_CHECK_PROGS([XSLTPROC], [xsltproc])
AM_CONDITIONAL([DBUS_HAVE_XSLTPROC], [test "x$XSLTPROC" != "x"])
### Ducktype/Yelp documentation
AC_PATH_PROG([DUCKTYPE],[ducktype],[no])
AC_PATH_PROG([YELP_BUILD],[yelp-build],[no])
AC_MSG_CHECKING([whether to build Ducktype documentation])
AS_IF([test "$DUCKTYPE" = "no"],[have_ducktype=no],[have_ducktype=yes])
AS_IF([test "$YELP_BUILD" = "no"],[have_yelp_build=no],[have_yelp_build=yes])
AS_IF([test "$enable_ducktype_docs" = "auto"],[
AS_IF([test "$have_ducktype" = "no" || test "$have_yelp_build" = "no"],[
enable_ducktype_docs=no
],[
enable_ducktype_docs=yes
])
])
AS_IF([test "$enable_ducktype_docs" = "yes"],[
AS_IF([test "$have_ducktype" = "no"],[
AC_MSG_ERROR([Building Ducktype docs explicitly required, but ducktype not found])
])
AS_IF([test "$have_yelp_build" = "no"],[
AC_MSG_ERROR([Building Ducktype docs explicitly required, but yelp-build not found])
])
])
AM_CONDITIONAL([DBUS_DUCKTYPE_DOCS_ENABLED],[test "$enable_ducktype_docs" = "yes"])
AC_MSG_RESULT([$enable_ducktype_docs])
### XML Documentation
AC_PATH_PROG(XMLTO, xmlto, no)
......@@ -1451,7 +1485,8 @@ AM_CONDITIONAL(DBUS_XML_DOCS_ENABLED, test x$enable_xml_docs = xyes)
AC_MSG_RESULT($enable_xml_docs)
AM_CONDITIONAL(DBUS_CAN_UPLOAD_DOCS,
[test x$enable_doxygen_docs = xyes && test x$enable_xml_docs = xyes])
[test x$enable_doxygen_docs = xyes && test x$enable_xml_docs = xyes &&
test x$enable_ducktype_docs = xyes])
#### Have to go $localstatedir->$prefix/var->/usr/local/var
......@@ -1818,7 +1853,9 @@ echo "
32-bit int: ${DBUS_INT32_TYPE}
16-bit int: ${DBUS_INT16_TYPE}
Doxygen: ${DOXYGEN:-not found}
xmlto: ${XMLTO:-not found}"
xmlto: ${XMLTO:-not found}
ducktype: ${DUCKTYPE:-not found}
yelp-build: ${YELP_BUILD:-not found}"
echo "
Rebuilding generated files: ${USE_MAINTAINER_MODE}
......@@ -1838,6 +1875,7 @@ echo "
Building systemd support: ${have_systemd}
Building X11 code: ${have_x11}
Building Doxygen docs: ${enable_doxygen_docs}
Building Ducktype docs: ${enable_ducktype_docs}
Building XML docs: ${enable_xml_docs}
Building launchd support: ${have_launchd}
Init scripts style: ${with_init_scripts}
......
......@@ -17,3 +17,12 @@ dbus-faq.html
dbus-docs
dbus-docs.tar.gz
doxygen.stamp
dbus-api-design.page
dbus-api-design.html
jquery.js
jquery.syntax.brush.html.js
jquery.syntax.core.js
jquery.syntax.js
jquery.syntax.layout.yelp.js
yelp.js
C.css
......@@ -31,6 +31,7 @@ STATIC_DOCS = \
dbus-specification.xml \
dbus-test-plan.xml \
dbus-tutorial.xml \
dbus-api-design.duck \
dcop-howto.txt \
introspect.xsl \
$(DTDS)
......@@ -51,8 +52,24 @@ STATIC_HTML = \
diagram.svg \
$(NULL)
# Static HTML helper files generated by yelp-build.
YELP_STATIC_HTML = \
yelp.js \
C.css \
jquery.js \
jquery.syntax.js \
jquery.syntax.brush.html.js \
jquery.syntax.core.js \
jquery.syntax.layout.yelp.js \
$(NULL)
dist_html_DATA += $(STATIC_HTML)
# Content HTML files generated by yelp-build.
YELP_HTML = \
dbus-api-design.html \
$(NULL)
XMLTO_HTML = \
dbus-faq.html \
dbus-specification.html \
......@@ -85,6 +102,16 @@ dbus.devhelp: $(srcdir)/doxygen_to_devhelp.xsl doxygen.stamp
$(XSLTPROC) -o $@ $< api/xml/index.xml
endif
if DBUS_DUCKTYPE_DOCS_ENABLED
html_DATA += $(YELP_HTML) $(YELP_STATIC_HTML)
%.page: %.duck
$(DUCKTYPE) -o $@ $<
%.html: %.page
$(YELP_BUILD) html $<
$(YELP_STATIC_HTML): $(YELP_HTML)
endif
# this assumes CREATE_SUBDIRS isn't set to YES in Doxyfile
# (which it isn't currently)
install-data-local:: doxygen.stamp
......@@ -113,13 +140,15 @@ BONUS_FILES = \
$(top_srcdir)/COPYING \
$(top_srcdir)/ChangeLog
dbus-docs: $(STATIC_DOCS) $(MAN_XML_FILES) $(dist_doc_DATA) $(dist_html_DATA) $(MAN_HTML_FILES) $(BONUS_FILES) doxygen.stamp $(XMLTO_HTML)
dbus-docs: $(STATIC_DOCS) $(MAN_XML_FILES) $(dist_doc_DATA) $(dist_html_DATA) $(MAN_HTML_FILES) $(BONUS_FILES) doxygen.stamp $(XMLTO_HTML) $(YELP_HTML) $(YELP_STATIC_HTML)
$(AM_V_at)rm -rf $@ $@.tmp
$(AM_V_GEN)$(MKDIR_P) $@.tmp/api
$(AM_V_at)cd $(srcdir) && cp $(STATIC_DOCS) @abs_builddir@/$@.tmp
$(AM_V_at)cd $(srcdir) && cp $(dist_doc_DATA) @abs_builddir@/$@.tmp
$(AM_V_at)cd $(srcdir) && cp $(STATIC_HTML) @abs_builddir@/$@.tmp
$(AM_V_at)cp $(XMLTO_HTML) @abs_builddir@/$@.tmp
$(AM_V_at)cp $(YELP_HTML) @abs_builddir@/$@.tmp
$(AM_V_at)cp $(YELP_STATIC_HTML) @abs_builddir@/$@.tmp
$(AM_V_at)cp $(MAN_HTML_FILES) @abs_builddir@/$@.tmp
$(AM_V_at)cp $(MAN_XML_FILES) @abs_builddir@/$@.tmp
$(AM_V_at)cp $(BONUS_FILES) @abs_builddir@/$@.tmp
......@@ -143,7 +172,7 @@ maintainer-upload-docs: dbus-docs.tar.gz dbus-docs
else
maintainer-upload-docs:
@echo "Can't upload documentation! Re-run configure with"
@echo " --enable-doxygen-docs --enable-xml-docs"
@echo " --enable-doxygen-docs --enable-xml-docs --enable-ducktype-docs"
@echo "and ensure that man2html is installed."
@false
endif
......@@ -152,6 +181,8 @@ CLEANFILES = \
$(man1_MANS) \
$(MAN_XML_FILES) \
$(XMLTO_HTML) \
$(YELP_HTML) \
$(YELP_STATIC_HTML) \
$(NULL)
clean-local:
......
This diff is collapsed.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment