[ocamldoc] Build-in Ocamldoc support

Typing 'make doc' will generate documentation for the libraries in xen-api-libs. The documentation is integrated in the xen-api documentation (the custom ocamldoc generator in xen-api.hg is used). This only works when xen-api.hg is present in myrepos and 'make doc' has been executed in it.

Signed-off-by: Rob Hoes <rob.hoes@citrix.com>

Makefile

@@ -142,6 +142,28 @@ api-libs: $(OUTPUT_API_PKG) $(MY_SOURCES)/MANIFEST
 .PHONY: xapi-libs
 xapi-libs: $(OUTPUT_XAPI_PKG) $(MY_SOURCES)/MANIFEST
 	@ :
+
+.PHONY: doc
+doc:
+	$(MAKE) -C stdext doc
+	$(MAKE) -C sexpr doc
+	$(MAKE) -C uuid doc
+	$(MAKE) -C log doc
+	$(MAKE) -C xb doc
+	$(MAKE) -C xc doc
+	$(MAKE) -C xs doc
+	$(MAKE) -C xml-light2 doc
+	$(MAKE) -C rpc-light doc
+	$(MAKE) -C http-svr doc
+	$(MAKE) -C camldm doc
+	$(MAKE) -C cdrom doc
+	$(MAKE) -C close-and-exec doc
+	$(MAKE) -C eventchn doc
+	$(MAKE) -C pciutil doc
+	$(MAKE) -C rss doc
+	$(MAKE) -C stunnel doc
+	$(MAKE) -C xsrpc doc
+	$(MAKE) -C mmap doc
 
 .PHONY: clean
 clean:
@@ -158,6 +180,7 @@ clean:
 	make -C http-svr clean
 	make -C close-and-exec clean
 	make -C sexpr clean
+	make -C doc clean
 	rm -f $(OUTPUT_API_PKG)
 
 cleanxen:

camldm/Makefile

@@ -18,6 +18,8 @@ OBJS = camldm
 INTF = $(foreach obj, $(OBJS),$(obj).cmi)
 LIBS = camldm.cma camldm.cmxa
 
+DOCDIR = /myrepos/xen-api-libs.hg/doc
+
 all: $(INTF) $(LIBS) $(PROGRAMS)
 
 bins: $(PROGRAMS)
@@ -60,5 +62,9 @@ install: $(LIBS) META
 uninstall:
 	ocamlfind remove camldm
 
+.PHONY: doc
+doc: $(INTF)
+	python ../doc/doc.py $(DOCDIR) "camldm" "library" "$(OBJS)" "." "" ""
+
 clean:
 	rm -f *.o *.so *.a *.cmo *.cmi *.cma *.cmx *.cmxa *.annot $(LIBS) $(PROGRAMS)

cdrom/Makefile

@@ -17,6 +17,8 @@ OBJS = cdrom
 INTF = $(foreach obj, $(OBJS),$(obj).cmi)
 LIBS = cdrom.cma cdrom.cmxa
 
+DOCDIR = /myrepos/xen-api-libs.hg/doc
+
 all: $(INTF) $(LIBS) $(PROGRAMS)
 
 bins: $(PROGRAMS)
@@ -59,6 +61,10 @@ install: $(LIBS) META
 uninstall:
 	ocamlfind remove cdrom
 
+.PHONY: doc
+doc: $(INTF)
+	python ../doc/doc.py $(DOCDIR) "cdrom" "library" "$(OBJS)" "." "" ""
+
 clean:
 	rm -f *.o *.so *.a *.cmo *.cmi *.cma *.cmx *.cmxa *.annot $(LIBS) $(PROGRAMS)
 

close-and-exec/Makefile

@@ -21,6 +21,8 @@ LIBS = closeandexec.cmxa closeandexec.cma
 
 PROGRAMS = closeandexec
 
+DOCDIR = /myrepos/xen-api-libs.hg/doc
+
 all: $(INTF) $(LIBS)
 
 bins: $(PROGRAMS)
@@ -68,5 +70,9 @@ uninstall:
 binuninstall:
 	rm -f $(DESTDIR)$(LIBEXEC)$(PROGRAMS)
 
+.PHONY: doc
+doc: $(INTF)
+	python ../doc/doc.py $(DOCDIR) "close-and-exec" "library" "$(OBJS)" "." "stdext" ""
+
 clean:
-	rm -f *.o *.so *.a *.cmo *.cmi *.cma *.cmx *.cmxa *.annot $(LIBS) $(PROGRAMS)
+	rm -f *.o *.so *.a *.cmo *.cmi *.cma *.cmx *.cmxa *.annot $(LIBS) $(PROGRAMS)

doc/doc.py

@@ -21,31 +21,28 @@
 
 docdir = sys.argv[1]
 name = sys.argv[2]
-ctype = sys.argv[3]
+if sys.argv[3] == "library": is_library = True
+else: is_library = False
 modules = set(sys.argv[4].split())
 includes = sys.argv[5].split()
-packs = sys.argv[6].replace(',',' ').split()
-libs = sys.argv[7].split()
-if len(sys.argv) >= 9:
-	pp = '-pp ' + sys.argv[8]
-else:
-	pp = ''
-
-libs = list(set(libs))	# remove duplicates
-packs = list(set(packs))	# remove duplicates
+packs = sys.argv[6]
+libs = sys.argv[7]
 
 dest = docdir + '/content/' + name
 try:
 	os.makedirs(dest)
 except:
 	pass
+
+packs = packs.replace(',', ' ')
+packs = packs.split()
 
 if len(packs) > 0:
-	packages = "-package " + ','.join(packs)
+	packages = "-package " + str(','.join(packs))
 else:
 	packages = ""
 
-doc_command = 'ocamlfind ocamldoc -v ' + packages + ' -I +threads -sort -g /myrepos/xen-api.hg/ocaml/doc/odoc_json.cma -d ' + dest + ' ' + pp
+doc_command = 'ocamlfind ocamldoc -v ' + packages + ' -I +threads -sort -g /myrepos/xen-api.hg/ocaml/doc/odoc_json.cma -d ' + dest + ' '
 
 files = []
 for m in modules:
@@ -64,13 +61,14 @@
 
 os.system(doc_command + ' ' + string.join(includesx) + ' ' + string.join(files))
 
-# add dependencies to index files
+# add library dependencies to index files
 
 f = file(dest + '/index.json', 'a')
-packs_s = map(lambda s: '"' + s.split('/')[-1] + '"', packs)
-libs_s = map(lambda s: '"' + s.split('/')[-1] + '"', libs)
-s = 'deps_' + name.replace("-", "") + ' = {"packs": [' + ', '.join(packs_s) + '], '
-s += '"libs": [' + ', '.join(libs_s) + ']}'
+libs = libs.split()
+libs.extend(packs)
+libs = map(lambda s: '"' + s.split('/')[-1] + '"', libs)
+libs = list(set(libs))	# remove duplicates
+s = 'deps_' + name.replace("-", "") + ' = [' + ', '.join(libs) + '];'
 f.write(s)
 f.close()
 
@@ -79,31 +77,25 @@
 def update_components(compdir):
 	executables = []
 	libraries = []
-	packages = []
-
+
 	try:
 		f = file(compdir + '/components.js', 'r')
 		exec(f.readline())
 		exec(f.readline())
-		exec(f.readline())
 		f.close()
 	except:
 		pass
 
-	if ctype == "library":
+	if is_library:
 		libraries.append(name)
 		libraries = list(set(libraries))
-	elif ctype == "package":
-		packages.append(name)
-		packages = list(set(packages))
 	else:
 		executables.append(name)
 		executables = list(set(executables))
 
 	f = file(compdir + '/components.js', 'w')
 	f.write('executables = ' + str(executables) + '\n')
-	f.write('libraries = ' + str(libraries) + '\n')
-	f.write('packages = ' + str(packages))
+	f.write('libraries = ' + str(libraries))
 	f.close()
 
 update_components(docdir)

eventchn/Makefile

@@ -17,6 +17,8 @@ OBJS = eventchn
 INTF = $(foreach obj, $(OBJS),$(obj).cmi)
 LIBS = eventchn.cma eventchn.cmxa
 
+DOCDIR = /myrepos/xen-api-libs.hg/doc
+
 all: $(INTF) $(LIBS) $(PROGRAMS)
 
 bins: $(PROGRAMS)
@@ -59,6 +61,10 @@ install: $(LIBS) META
 uninstall:
 	ocamlfind remove eventchn
 
+.PHONY: doc
+doc: $(INTF)
+	python ../doc/doc.py $(DOCDIR) "eventchn" "library" "$(OBJS)" "." "" ""
+
 clean:
 	rm -f *.o *.so *.a *.cmo *.cmi *.cma *.cmx *.cmxa *.annot $(LIBS) $(PROGRAMS)
 

http-svr/Makefile

@@ -17,6 +17,8 @@ OBJS = server_io buf_io http http_svr
 INTF = $(foreach obj, $(OBJS),$(obj).cmi)
 LIBS = http_svr.cma http_svr.cmxa
 
+DOCDIR = /myrepos/xen-api-libs.hg/doc
+
 all: $(INTF) $(LIBS)
 
 bins: $(PROGRAMS)
@@ -52,5 +54,9 @@ install: $(LIBS) META
 uninstall:
 	ocamlfind remove http-svr
 
+.PHONY: doc
+doc: $(INTF)
+	python ../doc/doc.py $(DOCDIR) "http-svr" "library" "$(OBJS)" "." "log,stdext" ""
+
 clean:
-	rm -f *.o *.so *.a *.cmo *.cmi *.cma *.cmx *.cmxa *.annot $(LIBS) $(PROGRAMS)
+	rm -f *.o *.so *.a *.cmo *.cmi *.cma *.cmx *.cmxa *.annot $(LIBS) $(PROGRAMS)

log/Makefile

@@ -19,6 +19,8 @@ OBJS = syslog log logs debug
 INTF = log.cmi logs.cmi syslog.cmi debug.cmi
 LIBS = log.cma log.cmxa
 
+DOCDIR = /myrepos/xen-api-libs.hg/doc
+
 all: $(INTF) $(LIBS) $(PROGRAMS)
 
 bins: $(PROGRAMS)
@@ -66,5 +68,9 @@ install: $(LIBS) META
 uninstall:
 	ocamlfind remove log
 
+.PHONY: doc
+doc: $(INTF)
+	python ../doc/doc.py $(DOCDIR) "log" "library" "$(OBJS)" "." "stdext" ""
+
 clean:
 	rm -f *.o *.so *.a *.cmo *.cmi *.cma *.cmx *.cmxa *.annot $(LIBS) $(PROGRAMS)

mmap/Makefile

@@ -17,6 +17,8 @@ OBJS = mmap
 INTF = $(foreach obj, $(OBJS),$(obj).cmi)
 LIBS = mmap.cma mmap.cmxa
 
+DOCDIR = /myrepos/xen-api-libs.hg/doc
+
 all: $(INTF) $(LIBS) $(PROGRAMS)
 
 bins: $(PROGRAMS)
@@ -59,6 +61,10 @@ install: $(LIBS) META
 uninstall:
 	ocamlfind remove mmap
 
+.PHONY: doc
+doc: $(INTF)
+	python ../doc/doc.py $(DOCDIR) "mmap" "library" "$(OBJS)" "." "" ""
+
 clean:
 	rm -f *.o *.so *.a *.cmo *.cmi *.cma *.cmx *.cmxa *.annot $(LIBS) $(PROGRAMS)
 

pciutil/Makefile

@@ -19,6 +19,8 @@ OBJS = pciutil
 INTF = $(foreach obj, $(OBJS),$(obj).cmi)
 LIBS = pciutil.cma pciutil.cmxa
 
+DOCDIR = /myrepos/xen-api-libs.hg/doc
+
 PROGRAMS = pciutil
 
 all: $(INTF) $(LIBS)
@@ -68,5 +70,9 @@ uninstall:
 binuninstall:
 	rm -f $(DESTDIR)$(LIBEXEC)$(PROGRAMS)
 
+.PHONY: doc
+doc: $(INTF)
+	python ../doc/doc.py $(DOCDIR) "pciutil" "library" "$(OBJS)" "." "stdext" ""
+
 clean:
-	rm -f *.o *.so *.a *.cmo *.cmi *.cma *.cmx *.cmxa *.annot $(LIBS) $(PROGRAMS)
+	rm -f *.o *.so *.a *.cmo *.cmi *.cma *.cmx *.cmxa *.annot $(LIBS) $(PROGRAMS)

rpc-light/Makefile

@@ -5,6 +5,8 @@ PACKS = xmlm
 
 ICAMLP4=-I $(shell ocamlfind query camlp4) -I $(shell ocamlfind query type-conv)
 
+DOCDIR = /myrepos/xen-api-libs.hg/doc
+
 .PHONY: all clean
 all: pa_rpc.cma xmlrpc.cmi xmlrpc.cma xmlrpc.cmxa jsonrpc.cmi jsonrpc.cmxa jsonrpc.cma
 
@@ -69,5 +71,9 @@ uninstall:
 	ocamlfind remove jsonrpc
 	ocamlfind remove rpc-light
 
+.PHONY: doc
+doc: $(INTF)
+	python ../doc/doc.py $(DOCDIR) "rpc-light" "library" "jsonrpc pa_rpc rpc xmlrpc" "." "xmlm" ""
+
 clean:
-	rm -f *.cmo *.cmx *.cma *.cmxa *.annot *.o *.cmi *.a
+	rm -f *.cmo *.cmx *.cma *.cmxa *.annot *.o *.cmi *.a

rss/Makefile

@@ -17,6 +17,8 @@ OBJS = rss
 INTF = $(foreach obj, $(OBJS),$(obj).cmi)
 LIBS = rss.cma rss.cmxa
 
+DOCDIR = /myrepos/xen-api-libs.hg/doc
+
 all: $(INTF) $(LIBS) $(PROGRAMS)
 
 bins: $(PROGRAMS)
@@ -52,5 +54,9 @@ install: $(LIBS) META
 uninstall:
 	ocamlfind remove rss
 
+.PHONY: doc
+doc: $(INTF)
+	python ../doc/doc.py $(DOCDIR) "rss" "library" "$(OBJS)" "." "xml-light2" ""
+
 clean:
-	rm -f *.o *.so *.a *.cmo *.cmi *.cma *.cmx *.cmxa *.annot $(LIBS) $(PROGRAMS)
+	rm -f *.o *.so *.a *.cmo *.cmi *.cma *.cmx *.cmxa *.annot $(LIBS) $(PROGRAMS)

sexpr/Makefile

@@ -23,6 +23,8 @@ LIBS = sexpr.cma sexpr.cmxa
 
 PROGRAMS = sexprpp
 
+DOCDIR = /myrepos/xen-api-libs.hg/doc
+
 all: $(INTF) $(LIBS)
 
 bins: $(PROGRAMS)
@@ -82,5 +84,9 @@ uninstall:
 binuninstall:
 	rm -f $(DESTDIR)$(LIBEXEC)$(PROGRAMS)
 
+.PHONY: doc
+doc: $(INTF)
+	python ../doc/doc.py $(DOCDIR) "sexpr" "library" "$(OBJS)" "." "stdext" ""
+
 clean:
-	rm -f *.o *.so *.a *.cmo *.cmi *.cma *.cmx *.cmxa *.annot sExprLexer.ml{,i} sExprParser.ml{,i} $(LIBS) $(PROGRAMS)
+	rm -f *.o *.so *.a *.cmo *.cmi *.cma *.cmx *.cmxa *.annot sExprLexer.ml{,i} sExprParser.ml{,i} $(LIBS) $(PROGRAMS)

stdext/Makefile

@@ -27,6 +27,8 @@ LIBS = stdext.cma stdext.cmxa
 
 PROGRAMS = base64pp
 
+DOCDIR = /myrepos/xen-api-libs.hg/doc
+
 all: $(INTF) $(LIBS)
 
 bins: $(PROGRAMS)
@@ -113,6 +115,10 @@ uninstall:
 binuninstall:
 	rm -f $(DESTDIR)$(LIBEXEC)$(PROGRAMS)
 
+.PHONY: doc
+doc: $(INTF)
+	python ../doc/doc.py $(DOCDIR) "stdext" "library" "$(STDEXT_OBJS)" "." "threads,uuid,unix" ""
+
 clean:
 	rm -f *.o *.so *.a *.cmo *.cmi *.cma *.cmx *.cmxa *.annot $(LIBS) $(PROGRAMS)
 
@@ -121,4 +127,4 @@ clean:
 unixext.cmi: filenameext.cmi
 gzip.cmi: forkhelpers.cmi
 sha1sum.cmi: forkhelpers.cmi
-tar.cmi: bigbuffer.cmi
+tar.cmi: bigbuffer.cmi