Makefile.doc

# -*- Makefile -*-

##### This is uesd to build the documentation at https://mrcal.secretsauce.net
##### The primary intent isn't for end-users to build these, so this isn't
##### well-tested in many scenarios. Expect fiddling with dependencies and such
##### if you need to re-build this stuff


# To use the latest tag in the documentation, run
#
# VERSION_USE_LATEST_TAG=1 make

## I generate a single mrcal-python-api-reference.html for ALL the Python code.
## This is large
DOC_HTML += doc/out/mrcal-python-api-reference.html
doc/out/mrcal-python-api-reference.html: $(wildcard mrcal/*.py) $(patsubst %,mrcal/%$(PY_EXT_SUFFIX),$(ALL_PY_EXTENSION_MODULES)) libmrcal.so.$(ABI_VERSION) | doc/out/
	python3 doc/pydoc.py -w mrcal > $@.tmp && mv $@.tmp $@

DOC_ALL_FIG          := $(wildcard doc/*.fig)
DOC_ALL_SVG_FROM_FIG := $(patsubst doc/%.fig,doc/out/figures/%.svg,$(DOC_ALL_FIG))
DOC_ALL_PDF_FROM_FIG := $(patsubst doc/%.fig,doc/out/figures/%.pdf,$(DOC_ALL_FIG))
doc: $(DOC_ALL_SVG_FROM_FIG) $(DOC_ALL_PDF_FROM_FIG)
$(DOC_ALL_SVG_FROM_FIG): doc/out/figures/%.svg: doc/%.fig | doc/out/figures/
	fig2dev -L svg $< $@
$(DOC_ALL_PDF_FROM_FIG): doc/out/figures/%.pdf: doc/%.fig | doc/out/figures/
	fig2dev -L pdf $< $@

DOC_ALL_DOT          := $(wildcard doc/*.dot)
DOC_ALL_TEX_FROM_DOT := $(patsubst doc/%.dot,doc/out/figures/%.tex,$(DOC_ALL_DOT))
DOC_ALL_PDF_FROM_DOT := $(patsubst %.tex,%.pdf,$(DOC_ALL_TEX_FROM_DOT))
doc: $(DOC_ALL_PDF_FROM_DOT)
# This is very error-prone for some reason. The below options and the existing
# doc/cross-uncertainty.dot work, but tweaking either makes it now work.
$(DOC_ALL_TEX_FROM_DOT): doc/out/figures/%.tex: doc/%.dot | doc/out/figures/
	dot2tex --autosize -c -t math $< -o $@
# pdflatex ignores the directory of the given argument, so I need to cd in there
# first
%.pdf: %.tex
	cd $(dir $@); pdflatex $(notdir $<)


## I'd like to place docs for each Python submodule in a separate .html (instead
## of a single huge mrcal-python-api-reference.html). Here's an attempt at at
## that. This works, but needs more effort:
##
## - top level mrcal.html is confused about what it contains. It has all of
##   _mrcal and _poseutils for some reason
## - cross-submodule links don't work
#
# doc-reference: \
# 	$(patsubst mrcal/%.py,doc/mrcal.%.html,$(filter-out %/__init__.py,$(wildcard mrcal/*.py))) \
# 	$(patsubst %,doc/out/mrcal.%.html,$(ALL_PY_EXTENSION_MODULES)) \
# 	doc/out/mrcal.html
# doc/out/mrcal.%.html: \
# 	mrcal/%.py \
# 	$(patsubst %,mrcal/%$(PY_EXT_SUFFIX),$(ALL_PY_EXTENSION_MODULES)) \
# 	libmrcal.so.$(ABI_VERSION)
# 	doc/pydoc.py -w mrcal.$* > $@.tmp && mv $@.tmp $@
# doc/out/mrcal.%.html: mrcal/%$(PY_EXT_SUFFIX)
# 	doc/pydoc.py -w mrcal.$* > $@.tmp && mv $@.tmp $@
# doc/out/mrcal.html: \
# 	$(wildcard mrcal/*.py) \
# 	$(patsubst %,mrcal/%$(PY_EXT_SUFFIX),$(ALL_PY_EXTENSION_MODULES)) \
# 	libmrcal.so.$(ABI_VERSION)
# 	doc/pydoc.py -w mrcal > $@.tmp && mv $@.tmp $@
# .PHONY: doc-reference



DOC_ALL_CSS        := $(wildcard doc/*.css)
DOC_ALL_CSS_TARGET := $(patsubst doc/%,doc/out/%,$(DOC_ALL_CSS))
doc: $(DOC_ALL_CSS_TARGET)
$(DOC_ALL_CSS_TARGET): doc/out/%.css: doc/%.css | doc/out/
	cp $< doc/out

DOC_ALL_ORG         := $(wildcard doc/*.org)
DOC_ALL_HTML_TARGET := $(patsubst doc/%.org,doc/out/%.html,$(DOC_ALL_ORG))
DOC_HTML += $(DOC_ALL_HTML_TARGET)

# This ONE command creates ALL the html files, so I want a pattern rule to indicate
# that. I want to do:
#   %/out/a.html %/out/b.html %/out/c.html: %/a.org %/b.org %/c.org
$(addprefix %,$(patsubst doc/%,/%,$(DOC_ALL_HTML_TARGET))): $(addprefix %,$(patsubst doc/%,/%,$(DOC_ALL_ORG)))
	emacs --chdir=doc -l mrcal-docs-publish.el --batch --eval '(load-library "org")' --eval '(org-publish-all t nil)'
$(DOC_ALL_HTML_TARGET): doc/mrcal-docs-publish.el | doc/out/


$(DIST_MAN): %.1: %.pod
	pod2man --center="mrcal: camera projection, calibration toolkit" --name=MRCAL --release="mrcal $(VERSION)" --section=1 $< $@
%.pod: %
	$(MRBUILD_BIN)/make-pod-from-help $< > $@.tmp && cat footer.pod >> $@.tmp && mv $@.tmp $@
EXTRA_CLEAN += $(DIST_MAN) $(patsubst %.1,%.pod,$(DIST_MAN))

# I generate a manpage. Some perl stuff to add the html preamble
MANPAGES_HTML := $(patsubst %,doc/out/%.html,$(DIST_BIN))
doc/out/%.html: %.pod | doc/out/
	pod2html --noindex --css=mrcal.css --infile=$< | \
	  perl -ne 'BEGIN {$$h = `cat doc/mrcal-preamble-GENERATED.html`;} if(!/(.*<body>)(.*)/s) { print; } else { print "$$1 $$h $$2"; }' > $@.tmp && mv $@.tmp $@

DOC_HTML += $(MANPAGES_HTML)

$(DOC_HTML): doc/mrcal-preamble-GENERATED.html
# If the git HEAD moves, I regenerate the preamble. It contains a version string
# that uses the git info. This still isn't complete. A new git tag SHOULD
# trigger this to be regenerated, but it doesn't. I'll do that later
doc/mrcal-preamble-GENERATED.html: doc/mrcal-preamble-TEMPLATE.html $(and $(wildcard .git),.git/$(shell cut -d' ' -f2 .git/HEAD))
	< $< sed s/@@VERSION@@/$(VERSION)/g > $@.tmp && mv $@.tmp $@
EXTRA_CLEAN += doc/mrcal-preamble-GENERATED.html

# Documentation uses the latest tag only to denote the version. This will only
# work properly after a 'make clean' (If you "make", everything is built without
# VERSION_USE_LATEST_TAG=1; then when you "make doc", the products built without
# VERSION_USE_LATEST_TAG=1 are used). Beware
doc: VERSION_USE_LATEST_TAG=1

doc: $(DOC_HTML) | doc/out/external
.PHONY: doc

doc/out/external:
	ln -fs ../../../mrcal-doc-external $@

# the whole output documentation directory
EXTRA_CLEAN += doc/out



# Convenience rules. Don't blindly use these if you aren't Dima and you aren't
# using his machine
publish-doc: doc
	rsync --exclude '*~' --exclude external -avu doc/out/ mrcal.secretsauce.net:/var/www/mrcal/docs-latest-release
publish-doc-external:
	rsync -avu ../mrcal-doc-external/ mrcal.secretsauce.net:/var/www/mrcal/docs-2.3/external
.PHONY: publish-doc publish-doc-external