# file: doc.mak
# description: Makefile submodule to build the documentation
# author: Andrea Vedaldi
# Copyright (C) 2007-12 Andrea Vedaldi and Brian Fulkerson.
# All rights reserved.
#
# This file is part of the VLFeat library and is made available under
# the terms of the BSD license (see the COPYING file).
info: doc-info
clean: doc-clean
distclean: doc-distclean
archclean: doc-archclean
# --------------------------------------------------------------------
# Configuration
# --------------------------------------------------------------------
DOXYGEN ?= doxygen
PDFLATEX ?= pdflatex
FIG2DEV ?= fig2dev
INKSCAPE ?= inkscape
CONVERT ?= convert
PYTHON ?= python
GROFF ?= groff
TIDY ?= tidy
MV ?= mv
SED ?= sed
# 95 DPI makes a letter page 808 pixels large
screen_dpi := 95
doc: doc-api doc-man doc-matlab
# generate doc-dir: target
$(eval $(call gendir, doc, \
doc \
doc/build doc/build/api doc/build/man doc/build/figures \
doc/demo doc/figures doc/matlab doc/api))
# generate results-dir: target
$(eval $(call gendir, results, results))
# --------------------------------------------------------------------
# MATLAB
# --------------------------------------------------------------------
.PHONY: doc-deep
ifdef MATLAB_PATH
doc-matlab: doc/matlab/helpsearch/deletable
endif
# use MATLAB to create the figures for the tutorials
doc-deep: all $(doc-dir) $(results-dir)
cd toolbox ; \
VL_DEMO_PRINT=y $(MATLAB_EXE) \
-$(ARCH) -nodesktop -nosplash \
-r "clear mex;vl_setup demo;vl_demo;exit"
@echo "Trimming images ..."
find doc/demo -name "*.jpg" -exec $(CONVERT) -trim "{}" "{}" ";"
@echo "Done trimming"
$(MAKE) doc
# make documentation searchable in MATLAB
doc/matlab/helpsearch/deletable : doc/build/matlab/helpsearch/deletable $(doc-dir)
cp -v doc/build/matlab/helptoc.xml doc/matlab/
cp -rv doc/build/matlab/helpsearch doc/matlab/
doc/build/matlab/helpsearch/deletable: doc/build/matlab/helptoc.xml
$(MATLAB_EXE) -$(ARCH) -nodisplay -r "builddocsearchdb('doc/build/matlab/') ; exit"
# --------------------------------------------------------------------
# MDoc
# --------------------------------------------------------------------
doc-matlab: doc/build/matlab/mdoc.html
#
# Use mdoc.py to create the toolbox documentation that will be
# embedded in the website.
#
doc/build/matlab/mdoc.html doc/build/matlab/helptoc.xml: \
$(m_src) \
docsrc/mdoc.py #make/doc.mak
$(PYTHON) docsrc/mdoc.py toolbox doc/build/matlab \
--format=web \
--exclude='noprefix/.*' \
--exclude='xtune/.*' \
--exclude='xtest/.*' \
--exclude='.*/vl_test_.*' \
--exclude='.*/vl_demo_.*' \
--exclude='.*/vl_tune_.*' \
--helptoc \
--helptoc-toolbox-name VLFeat \
--verbose
# --------------------------------------------------------------------
# Auto-include demo m-files
# --------------------------------------------------------------------
m_demo_src=$(wildcard toolbox/demo/vl_demo_*.m)
# Convert the various man pages
doc/build/matlab/demo.xml : $(m_demo_src) $(doc-dir) make/doc.mak
@echo "Indexing demo files -> $@"
@( \
echo '<!DOCTYPE group PUBLIC ' ; \
echo ' "-//W3C//DTD XHTML 1.0 Transitional//EN"' ; \
echo ' "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">' ; \
echo "<group>" ; \
for fullName in $(m_demo_src) ; \
do \
fileName=$${fullName#toolbox/demo/} ; \
stem=$${fileName%.*} ; \
( \
echo "<page id='$${stem}' name='$${stem}' title='$${stem}' hide='yes'>" ; \
printf "<h1>Source code for <code>%s.m</code></h1>" "$${stem}"; \
echo "<p>This file is located in the <code>toolbox/demo</code> folder in VLFeat package.</p>" ; \
echo "<precode type='matlab'>" ; \
echo "<include src='toolbox/demo/$${fileName}' type='text'/>" ; \
echo "</precode>" ; \
echo "</page>" \
) ; \
done ; \
echo "</group>" ; \
) > "$@"
# --------------------------------------------------------------------
# Man
# --------------------------------------------------------------------
doc-man: doc/build/man/xman.xml doc/build/man/xman.html
man_src := $(wildcard src/*.1) $(wildcard src/*.7)
man_tgt := $(subst src/,doc/build/man/,$(addsuffix .html,$(man_src)))
doc/build/man/index.html : $(doc-dir)
# Integrate in Webdoc
doc/build/man/xman.xml : $(man_tgt) $(doc-dir)
@echo "Generating MAN XML webdooc document $@"
@echo "<group>" > "$@"
@for fullName in $(man_src) ; \
do \
fileName=$${fullName#src/} ; \
stem=$${fileName%.*} ; \
( \
echo "<page id='man.$${stem}' name='$${stem}' title='$${stem}'>" ; \
echo "<include src='doc/build/man/$${fileName}.html'/>" ; \
echo "</page>" \
) >> "$@" ; \
done
echo "</group>" >> "$@"
# Index page
doc/build/man/xman.html : $(man_tgt) $(doc-dir)
@echo "Generating MAN HTML index page $@"
@echo "<ul>" > "$@"
@for fullName in $(man_src) ; \
do \
fileName=$${fullName#src/} ; \
stem=$${fileName%.*} ; \
echo "<li><a href='%pathto:man.$${stem};'>$${stem}</a></li>" >> "$@" ; \
done
echo "</ul>" >> "$@"
# Convert the various man pages
doc/build/man/%.html : src/% $(doc-dir)
@$(print-command MAN2HTML, $@)
@( \
echo '<!DOCTYPE group PUBLIC ' ; \
echo ' "-//W3C//DTD XHTML 1.0 Transitional//EN"' ; \
echo ' "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">' ; \
echo "<group>" ; \
$(GROFF) -mandoc -Thtml < "$<" | \
$(TIDY) -asxhtml 2>/dev/null | \
sed -e '1,/<body>/ d' -e '/<\/body>/,$$ d' ; \
echo "</group>" \
) > "$@"
# --------------------------------------------------------------------
# FIG and SVG figures and images
# --------------------------------------------------------------------
doc_fig_src := $(wildcard docsrc/figures/*.fig)
doc_svg_src := $(wildcard docsrc/figures/*.svg)
doc_fig_tgt += $(subst docsrc/,doc/,$(doc_fig_src:.fig=.png)) $(subst docsrc/,doc/,$(doc_svg_src:.svg=.png))
.PRECIOUS: doc/build/figures/%.pdf
.PRECIOUS: doc/build/figures/%.tex
doc/figures/%.png : doc/build/figures/%.pdf
$(call C,CONVERT) -density 300 "$<" -resample $(screen_dpi) -trim "$@"
# Inkscape
doc/build/figures/%-raw.pdf doc/build/figures/%-raw.tex: docsrc/figures/%.svg
$(call C,INKSCAPE) --export-pdf=doc/build/figures/$(*)-raw.pdf --export-latex "$<"
@$(MV) doc/build/figures/$(*)-raw.pdf_tex doc/build/figures/$(*)-raw.tex
@$(SED) -e 's/$(*)-raw/doc\/build\/figures\/$(*)-raw/g' -i.bak 'doc/build/figures/$(*)-raw.tex'
# Fig
doc/build/figures/%-raw.tex : docsrc/figures/%.fig $(doc-dir)
$(call C,FIG2DEV) -L pdftex_t -p doc/build/figures/$*-raw.pdf "$<" "$@"
doc/build/figures/%-raw.pdf : docsrc/figures/%.fig $(doc-dir)
$(call C,FIG2DEV) -L pdftex "$<" "$@"
doc/build/figures/%.pdf doc/build/figures/%.aux doc/build/figures/%.log : \
doc/build/figures/%.tex doc/build/figures/%-raw.tex doc/build/figures/%-raw.pdf $(doc-dir)
$(call C,PDFLATEX) -shell-escape -interaction=batchmode -output-directory="$(dir $@)" "$<" 2>/dev/null
doc/build/figures/%.tex : $(doc-dir)
@$(print-command GEN, $@)
@/bin/echo '\documentclass[landscape]{article}' >$@
@/bin/echo '\usepackage[paper=a2paper,margin=0pt]{geometry}' >>$@
@/bin/echo '\usepackage{graphicx,color}' >>$@
@/bin/echo '\begin{document}' >>$@
@/bin/echo '\pagestyle{empty}' >>$@
@/bin/echo '\input{doc/build/figures/$(*)-raw.tex}' >>$@
@/bin/echo '\end{document}' >>$@
# --------------------------------------------------------------------
# Doxygen
# --------------------------------------------------------------------
doc-api: doc/api/index.html
doc/api/index.html: docsrc/doxygen.conf docsrc/vlfeat.bib VERSION \
$(dll_src) $(dll_hdr) $(doc_fig_tgt) toolbox/mexutils.h \
doc/build/doxygen_header.html doc/build/doxygen_footer.html
ln -sf docsrc/vlfeat.bib vlfeat.bib
$(DOXYGEN) $< 2>&1 | sed -e 's/Warning:/warning: /g'
rm vlfeat.bib
cp -fv docsrc/doxygen.css doc/api/doxygen.css
# --------------------------------------------------------------------
# Webdoc
# --------------------------------------------------------------------
webdoc_src = $(wildcard docsrc/*.xml) $(wildcard docsrc/*.html)
doc: doc/index.html doc/vlfeat.css doc/pygmentize.css $(doc_fig_tgt)
# prebuild to generate doxygen header and footer
doc/build/doxygen_header.html doc/build/doxygen_footer.html: $(webdoc_src) $(doc-dir)
VERSION=$(VER) $(PYTHON) docsrc/webdoc.py \
--outdir=doc/build/ \
--verbose \
docsrc/vlfeat-website-preproc.xml
cat doc/build/api/index.html | \
sed -n '/<!-- Doc Here -->/q;p' > doc/build/doxygen_header.html
echo '<div id="top">' >> doc/build/doxygen_header.html
cat doc/build/api/index.html | \
sed -n '/<!-- Doc Here -->/,$$p' > doc/build/doxygen_footer.html
doc/vlfeat.css : docsrc/vlfeat.css
cp -fv "$<" "$@"
doc/pygmentize.css : docsrc/pygmentize.css
cp -fv "$<" "$@"
# build: this is the last step integrating all documentation
doc/index.html: $(webdoc_src) $(doc-dir) \
doc/api/index.html \
doc/build/matlab/mdoc.html \
doc/build/man/xman.xml \
doc/build/man/xman.html \
doc/build/matlab/demo.xml \
docsrc/webdoc.py \
$(html_src)
cp doc/api/index.html doc/api/index.html.bak
VERSION=$(VER) $(PYTHON) docsrc/webdoc.py \
--outdir=doc \
--verbose \
--doxytag=doc/doxygen.tag \
--doxydir=api \
docsrc/vlfeat-website.xml
mv doc/api/index.html.bak doc/api/index.html
rsync -r docsrc/images doc/
# --------------------------------------------------------------------
# Maintenance and others
# --------------------------------------------------------------------
.PHONY: doc-clean, doc-archclean, doc-distclean
no_dep_targets := doc-clean doc-archclean doc-distclean
VERSION: vl/generic.h
echo "$(VER)" > VERSION
doc-clean:
rm -rf doc/build
doc-archclean:
doc-distclean:
rm -f docsrc/*.pyc
rm -rf doc
# --------------------------------------------------------------------
# Debug Makefile
# --------------------------------------------------------------------
.PHONY: doc-info
doc-info :
$(call echo-title,Documentation)
$(call dump-var,man_src)
$(call dump-var,fig_src)
$(call dump-var,demo_src)
$(call dump-var,pdf_tgt)
$(call dump-var,eps_tgt)
$(call dump-var,png_tgt)
$(call dump-var,jpg_tgt)
$(call dump-var,man_tgt)
$(call dump-var,DOXYGEN)
@echo
# --------------------------------------------------------------------
# Xcode Support
# --------------------------------------------------------------------
.PHONY: dox-
dox- : dox
.PHONY: dox-clean
dox-clean:
# Local variables:
# mode: Makefile
# End: