tools: overhaul haddock generation, publish combined api & internal haddocks
This commit is contained in:
Simon Michael
parent
4a7ad12271
commit
54f07f6ae7
135
Makefile
135
Makefile
@ -35,12 +35,20 @@ INCLUDEPATHS=\
|
|||||||
-ihledger-vty \
|
-ihledger-vty \
|
||||||
-ihledger-chart
|
-ihledger-chart
|
||||||
MAIN=hledger/hledger.hs
|
MAIN=hledger/hledger.hs
|
||||||
|
# all source files in the project (plus a few strays like Setup.hs & hlint.hs)
|
||||||
SOURCEFILES:= \
|
SOURCEFILES:= \
|
||||||
hledger/*hs \
|
hledger/*hs \
|
||||||
hledger/Hledger/*/*hs \
|
hledger/Hledger/*/*hs \
|
||||||
hledger-*/*hs \
|
hledger-*/*hs \
|
||||||
hledger-*/Hledger/*hs \
|
hledger-*/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
|
VERSIONHS=hledger/Hledger/Cli/Version.hs
|
||||||
CABALFILES:= \
|
CABALFILES:= \
|
||||||
hledger/hledger.cabal \
|
hledger/hledger.cabal \
|
||||||
@ -289,7 +297,7 @@ doctest: tools/doctest
|
|||||||
|
|
||||||
# make sure we have no haddock errors
|
# make sure we have no haddock errors
|
||||||
haddocktest:
|
haddocktest:
|
||||||
@(make --quiet haddock \
|
@(make --quiet codehaddock \
|
||||||
&& echo $@ PASSED) || echo $@ FAILED
|
&& echo $@ PASSED) || echo $@ FAILED
|
||||||
|
|
||||||
# make sure the normal build has no warnings
|
# make sure the normal build has no warnings
|
||||||
@ -422,7 +430,7 @@ cleandocs:
|
|||||||
rm -rf site/[A-Z]*.html site/api-doc/*
|
rm -rf site/[A-Z]*.html site/api-doc/*
|
||||||
|
|
||||||
# rebuild all docs
|
# rebuild all docs
|
||||||
docs: site apidocs
|
docs: site codedocs
|
||||||
|
|
||||||
# build the hledger.org website
|
# build the hledger.org website
|
||||||
# Requires hakyll (cabal install hakyll)
|
# Requires hakyll (cabal install hakyll)
|
||||||
@ -431,9 +439,11 @@ site: site/hakyll site/_site/index.html site/_site/profs
|
|||||||
cd site; ./hakyll build
|
cd site; ./hakyll build
|
||||||
|
|
||||||
site/_site/index.html:
|
site/_site/index.html:
|
||||||
|
mkdir -p site/_site
|
||||||
cd site/_site; ln -sf README.html index.html; ln -sf ../../profs
|
cd site/_site; ln -sf README.html index.html; ln -sf ../../profs
|
||||||
|
|
||||||
site/_site/profs:
|
site/_site/profs:
|
||||||
|
mkdir -p site/_site
|
||||||
cd site/_site; ln -sf ../../profs
|
cd site/_site; ln -sf ../../profs
|
||||||
|
|
||||||
cleansite: site/hakyll
|
cleansite: site/hakyll
|
||||||
@ -489,61 +499,92 @@ printall: pdf
|
|||||||
pushdocs: push
|
pushdocs: push
|
||||||
ssh simon@joyful.com 'make -C/repos/hledger docs'
|
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:
|
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:
|
||||||
-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
|
#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
|
#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
|
#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
|
# RELEASING
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user