tools: overhaul haddock generation, publish combined api & internal haddocks

Makefile

@@ -35,12 +35,20 @@ INCLUDEPATHS=\
 	-ihledger-vty \
 	-ihledger-chart
 MAIN=hledger/hledger.hs
+# all source files in the project (plus a few strays like Setup.hs & hlint.hs)
 SOURCEFILES:= \
 	hledger/*hs \
 	hledger/Hledger/*/*hs \
 	hledger-*/*hs \
 	hledger-*/Hledger/*hs \
 	hledger-*/Hledger/*/*hs
+# a more careful list suitable for for haddock
+SOURCEFILESFORHADDOCK:= \
+	hledger-lib/Hledger/*hs \
+	hledger-lib/Hledger/*/*hs \
+	hledger/Hledger/Cli/*hs \
+	hledger-web/Hledger/*/*hs \
+	hledger-vty/Hledger/*hs
 VERSIONHS=hledger/Hledger/Cli/Version.hs
 CABALFILES:= \
 	hledger/hledger.cabal \
@@ -289,7 +297,7 @@ doctest: tools/doctest
 
 # make sure we have no haddock errors
 haddocktest:
-	@(make --quiet haddock \
+	@(make --quiet codehaddock \
 		&& echo $@ PASSED) || echo $@ FAILED
 
 # make sure the normal build has no warnings
@@ -422,7 +430,7 @@ cleandocs:
 	rm -rf site/[A-Z]*.html site/api-doc/*
 
 # rebuild all docs
-docs: site apidocs
+docs: site codedocs
 
 # build the hledger.org website
 # Requires hakyll (cabal install hakyll)
@@ -431,9 +439,11 @@ site: site/hakyll site/_site/index.html site/_site/profs
 	cd site; ./hakyll build
 
 site/_site/index.html:
+	mkdir -p site/_site
 	cd site/_site; ln -sf README.html index.html; ln -sf ../../profs
 
 site/_site/profs:
+	mkdir -p site/_site
 	cd site/_site; ln -sf ../../profs
 
 cleansite: site/hakyll
@@ -489,61 +499,92 @@ printall: pdf
 pushdocs: push
 	ssh simon@joyful.com 'make -C/repos/hledger docs'
 
-# generate api docs
+# generate api & other code docs
-# We munge haddock and hoogle into a rough but useful framed layout.
+codedocs: hscolour apihaddock codehaddock #sourcegraph #hoogle
-# For this to work the hoogle cgi must be built with base target "main".
-# XXX move the framed index building into haddock: ?
-apidocs: haddock hscolour #sourcegraph #hoogle
-	sed -i -e 's%^></HEAD%><base target="main"></HEAD%' site/api-doc/modules-index.html ; \
-	cp site/api-doc-frames.html site/api-doc/index.html ; \
-# 	cp site/hoogle-small.html site/api-doc
 
-# generate and view the api docs
+# browse the code docs
-viewapidocs: apidocs
+viewcodedocs:
-	$(VIEWHTML) site/api-doc/index.html
+	$(VIEWHTML) site/code-doc/index.html
 
-# generate code documentation with haddock
+#http://www.haskell.org/haddock/doc/html/invoking.html
-# --ignore-all-exports means we are documenting internal implementation, not library api
+#$(subst -D,--optghc=-D,$(DEFINEFLAGS))
-HADDOCK=haddock -B `ghc --print-libdir` $(subst -D,--optghc=-D,$(DEFINEFLAGS)) --ignore-all-exports --no-warnings
+HADDOCK=haddock --optghc='-hide-package monads-tf' --no-warnings --prologue .haddockprologue
-haddock:
-	$(HADDOCK) -o site/api-doc -h --source-module=src-%{MODULE/./-}.html --source-entity=src-%{MODULE/./-}.html#%N $(MAIN) && \
-		cp site/api-doc/index.html site/api-doc/modules-index.html
-	cd hledger-lib; cabal haddock
 
-HSCOLOUR=HsColour -css 
+.haddocksynopsis: hledger/hledger.cabal
+	grep synopsis $< | sed -e 's/synopsis: *//' >$@
+
+.haddockprologue: hledger/hledger.cabal
+	cat $< | perl -ne 'print if (/^description:/../^$$/)' | sed -e 's/^description: *//' >$@
+	printf "\nThis haddock covers all hledger-* packages, for individual package haddocks see hackage.\n" >>$@
+
+# generate external api docs for the whole project
+apihaddock: linkhledgerwebdir .haddockprologue
+	$(HADDOCK) --title "hledger API docs (all packages)" \
+	 -o site/api-doc \
+	 --html \
+	 --source-module=../code-doc/src/%{MODULE/./-}.html \
+	 --source-entity=../code-doc/src/%{MODULE/./-}.html#%N \
+	 $(SOURCEFILESFORHADDOCK)
+
+# generate internal code docs for the whole project
+codehaddock: linkhledgerwebdir .haddockprologue
+	$(HADDOCK) --title "hledger internal code docs (all packages)" \
+	 -o site/code-doc \
+	 --ignore-all-exports \
+	 --html \
+	 --source-module=../code-doc/src/%{MODULE/./-}.html \
+	 --source-entity=../code-doc/src/%{MODULE/./-}.html#%N \
+	 $(SOURCEFILESFORHADDOCK)
+
+#http://www.cs.york.ac.uk/fp/darcs/hscolour/
+HSCOLOUR=HsColour -icss
 hscolour:
-	for f in $(SOURCEFILES); do \
+	mkdir -p site/code-doc/src
-		$(HSCOLOUR) -anchor $$f -osite/api-doc/`echo "src/"$$f | sed -e's%/%-%g' | sed -e's%\.hs$$%.html%'` ; \
+	for f in $(SOURCEFILESFORHADDOCK); do \
-	done ; \
+		$(HSCOLOUR) -anchor $$f -osite/code-doc/src/`echo $$f | sed -e's%[^/]*/%%' | sed -e's%/%-%g' | sed -e's%\.hs$$%.html%'` ; \
-	cp site/api-doc/src-hledger.html site/api-doc/src-Main.html ; \
+	done
-	HsColour -print-css >site/api-doc/hscolour.css
 
 sourcegraph:
-	-SourceGraph hledger.cabal
+	for p in $(PACKAGES); do (cd $$p; SourceGraph $$p.cabal); done
-	-cd hledger-lib; SourceGraph hledger-lib.cabal
+
+# # generate external api docs for each package
+# allhaddock: allcabalhaddock\ --hyperlink-source\ --executables
+
+# # generate internal code docs for each package
+# allhaddockinternal: allcabalhaddock\ --hyperlink-source\ --executables\ --internal
+
+# # generate hoogle indices for each package
+# allhoogle: allcabalhaddock\ --hoogle\ --executables
 
 #set up the hoogle web interface
+## We munge haddock and hoogle into a rough but useful framed layout.
+## For this to work the hoogle cgi must be built with base target "main".
+## XXX move the framed index building into haddock: ?
+# 	sed -i -e 's%^></HEAD%><base target="main"></HEAD%' site/api-doc/modules-index.html ; \
+# 	cp site/api-doc-frames.html site/api-doc/index.html ; \
+# # 	cp site/hoogle-small.html site/api-doc
+#
 #uses a hoogle source tree configured with --datadir=., patched to fix haddock urls/target frame
-HOOGLESRC=/usr/local/src/hoogle
+# HOOGLESRC=/usr/local/src/hoogle
-HOOGLE=$(HOOGLESRC)/dist/build/hoogle/hoogle
+# HOOGLE=$(HOOGLESRC)/dist/build/hoogle/hoogle
-HOOGLEVER=`$(HOOGLE) --version |tail -n 1 | sed -e 's/Version /hoogle-/'`
+# HOOGLEVER=`$(HOOGLE) --version |tail -n 1 | sed -e 's/Version /hoogle-/'`
-hoogle: hoogleindex
+# hoogle: hoogleindex
-	if test -f $(HOOGLE) ; then \
+# 	if test -f $(HOOGLE) ; then \
-		cd site/api-doc && \
+# 		cd site/api-doc && \
-		rm -f $(HOOGLEVER) && \
+# 		rm -f $(HOOGLEVER) && \
-		ln -s . $(HOOGLEVER) && \
+# 		ln -s . $(HOOGLEVER) && \
-		cp -r $(HOOGLESRC)/src/res/ . && \
+# 		cp -r $(HOOGLESRC)/src/res/ . && \
-		cp -p $(HOOGLE) index.cgi && \
+# 		cp -p $(HOOGLE) index.cgi && \
-		touch log.txt && chmod 666 log.txt ; \
+# 		touch log.txt && chmod 666 log.txt ; \
-	else \
+# 	else \
-		echo "Could not find $(HOOGLE) in the hoogle source tree" ; \
+# 		echo "Could not find $(HOOGLE) in the hoogle source tree" ; \
-	fi
+# 	fi
-
+#
 #generate a hoogle index
-hoogleindex:
+# hoogleindex:
-	$(HADDOCK) -o site/api-doc --hoogle $(MAIN) && \
+# 	$(HADDOCK) -o site/api-doc --hoogle $(MAIN) && \
-	cd site/api-doc && \
+# 	cd site/api-doc && \
-	hoogle --convert=main.txt --output=default.hoo
+# 	hoogle --convert=main.txt --output=default.hoo
 
 ######################################################################
 # RELEASING