Add AMI event documentation

This patch adds the core changes necessary to support AMI event documentation
in the source files of Asterisk, and adds documentation to those AMI events
defined in the core application modules.  Event documentation is built from
the source by two new python scripts, located in build_tools:
get_documentation.py and post_process_documentation.py.

The get_documentation.py script mirrors the actions of the existing AWK
get_documentation scripts, except that it will scan the entirety of a source
file for Asterisk documentation.  Upon encountering it, if the documentation
happens to be an AMI event, it will attempt to extract information about the
event directly from the manager event macro calls that raise the event.  The
post_process_documentation.py script combines manager event instances that
are the same event but documented in multiple source files.  It generates
the final core-[lang].xml file.

As this process can take longer to complete than a typical 'make all', it
is only performed if a new make target, 'full', is chosen.

Review: https://reviewboard.asterisk.org/r/1967/

git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@369346 65c4cc65-6c06-0410-ace0-fbb531ad65f3

1 files changed, 40 insertions, 0 deletions

diff --git a/Makefile b/Makefile
index 51a7a065c..d6ed9198a 100644
--- a/Makefile
+++ b/Makefile
@@ -96,6 +96,7 @@ export MD5
 export WGET_EXTRA_ARGS
 export LDCONFIG
 export LDCONFIG_FLAGS
+export PYTHON
 
 # even though we could use '-include makeopts' here, use a wildcard
 # lookup anyway, so that make won't try to build makeopts if it doesn't
@@ -315,13 +316,29 @@ all: _cleantest_all
 	@echo " +               $(mK) install               +"
 	@echo " +-------------------------------------------+"
 
+full: _cleantest_all_full
+	@echo " +--------- Asterisk Build Complete ---------+"
+	@echo " + Asterisk has successfully been built, and +"
+	@echo " + can be installed by running:              +"
+	@echo " +                                           +"
+	@echo " +               $(mK) install               +"
+	@echo " +-------------------------------------------+"
+
+
 # For parallel builds, we must call cleantest *before* running the
 # other dependencies on _all.
 _cleantest_all: cleantest
 	@$(MAKE) _all
 
+# For parallel builds, we must call cleantest *before* running the
+# other dependencies on _all.
+_cleantest_all_full: cleantest
+	@$(MAKE) _all_full
+
 _all: makeopts $(SUBDIRS) doc/core-en_US.xml $(ADDL_TARGETS)
 
+_all_full: makeopts $(SUBDIRS) doc/full-en_US.xml $(ADDL_TARGETS)
+
 makeopts: configure
 	@echo "****"
 	@echo "**** The configure script must be executed before running '$(MAKE)'."
@@ -413,6 +430,8 @@ _clean:
 	rm -f defaults.h
 	rm -f include/asterisk/build.h
 	rm -f main/version.c
+	rm -f doc/core-en_US.xml
+	rm -f doc/full-en_US.xml
 	@$(MAKE) -C menuselect clean
 	cp -f .cleancount .lastclean
 
@@ -465,6 +484,27 @@ doc/core-en_US.xml: $(foreach dir,$(MOD_SUBDIRS),$(shell $(GREP) -l "language=\"
 	@echo
 	@echo "</docs>" >> $@
 
+doc/full-en_US.xml: $(foreach dir,$(MOD_SUBDIRS),$(shell $(GREP) -l "language=\"en_US\"" $(dir)/*.c $(dir)/*.cc 2>/dev/null))
+ifeq ($(PYTHON),:)
+	@echo "--------------------------------------------------------------------------"
+	@echo "---        Please install python to build full documentation           ---"
+	@echo "--------------------------------------------------------------------------"
+else
+	@printf "Building Documentation For: "
+	@echo "<?xml version=\"1.0\" encoding=\"UTF-8\"?>" > $@
+	@echo "<!DOCTYPE docs SYSTEM \"appdocsxml.dtd\">" >> $@
+	@echo "<docs xmlns:xi=\"http://www.w3.org/2001/XInclude\">" >> $@
+	@for x in $(MOD_SUBDIRS); do \
+		printf "$$x " ; \
+		for i in $$x/*.c; do \
+			$(PYTHON) build_tools/get_documentation.py < $$i >> $@ ; \
+		done ; \
+	done
+	@echo
+	@echo "</docs>" >> $@
+	@$(PYTHON) build_tools/post_process_documentation.py -i $@ -o "doc/core-en_US.xml"
+endif
+
 validate-docs: doc/core-en_US.xml
 ifeq ($(XMLSTARLET)$(XMLLINT),::)
 	@echo "--------------------------------------------------------------------------"