ドキュメント作成用の Makefile

ドキュメント用の Makefile

仕事で Markdown 形式のドキュメントをつくることになったので、 そのための Makefile を作った。 pdf 生成と redpen でのチェックをするようにしたい。

.PHONY: help clean redpen docs

.DEFAULT_GOAL = help

# define docker container for each targets
# container.redpen = ainoya/redpen
container.redpen = pandoc
container.docs = pandoc

all: docs

help:
   @grep -E '^[a-zA-Z%_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-30s\033[0m %s\n", $$1, $$2}'

docs: golang.pdf python.pdf ## generate pdf files

%.pdf: %.md
  pandoc $< --toc --from=gfm -t html5 -o $@

docker-%: ## run make in the Docker container (ex, 'make docker-docs' runs 'make docs' on the docker container)
  $(eval target = $(subst docker-,,$@))
  docker run -v `pwd`:/root/docs -it $(container.$(target)) $(option.$(target)) /bin/bash -c "cd /root/docs; make $(target)"

install-dev-mac: ## install developer's file
  brew install pandoc
  brew install redpen
  brew install graphviz
  brew install plantuml
  brew cask install wkhtmltopdf

redpen:
  redpen --conf redpen-conf.xml --format markdown --result-format plain2 -L ja *.md

clean:
  rm -rf *.pdf

ポイントとしては、自己文書化していることと Docker 上で走らせられるようにしてあることの 2 点がある。

自己文書化のアイディアはhttps://postd.cc/auto-documented-makefile/から持ってきている。 make help を実行すると次のように表示される。

docker-%                       run make in the Docker container (ex, 'make docker-docs' runs 'make docs' on the docker container)
docs                           generate pdf files
install-dev-mac                install developer's file

また docker- をルールの前に付けると、そのルールを Docker 上で実行する。 Docker で環境を共有するようにしたほうがいいかと思ったが、これについてはオーバースペックと言われた。

他にも色々出来そうだが、文章を書くことが優先事項なので後は手が空いたら改良したい。