From ad88794506a0ccf0671dd9b909890e0a80b346cc Mon Sep 17 00:00:00 2001 From: Stanislaw Klekot Date: Mon, 30 Oct 2017 20:39:07 +0100 Subject: Add support for Sphinx documentation builder --- test/plugin_sphinx.mk | 180 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 180 insertions(+) create mode 100644 test/plugin_sphinx.mk (limited to 'test') diff --git a/test/plugin_sphinx.mk b/test/plugin_sphinx.mk new file mode 100644 index 0000000..a31475a --- /dev/null +++ b/test/plugin_sphinx.mk @@ -0,0 +1,180 @@ +# Sphinx plugin. + +SPHINX_CASES = build source-dir formats format-opts +SPHINX_TARGETS = $(addprefix sphinx-,$(SPHINX_CASES)) + +.PHONY: sphinx $(SPHINX_TARGETS) + +sphinx: $(SPHINX_TARGETS) + +sphinx-build: build clean + + $i "Bootstrap a new OTP application named $(APP)" + $t mkdir $(APP)/ + $t cp ../erlang.mk $(APP)/ + $t $(MAKE) -C $(APP) -f erlang.mk bootstrap $v + + $i "Generate Sphinx config" + $(call sphinx-generate-doc-skeleton) + + $i "Run Sphinx" + $t $(MAKE) -C $(APP) sphinx $v + + $i "Check that documentation was generated" + $t test -f $(APP)/html/index.html + $t test -f $(APP)/html/manpage.html + + $i "Distclean the application" + $t $(MAKE) -C $(APP) distclean $v + + $i "Check that the generated documentation was removed" + $t test ! -e $(APP)/html/index.html + $t test ! -e $(APP)/html/manpage.html + + $i "Set 'today' macro with command-line options" + $t echo "SPHINX_OPTS = -D 'today=erlang_mk_sphinx_today'" >> $(APP)/Makefile + + $i "Run Sphinx" + $t $(MAKE) -C $(APP) sphinx $v + + $i "Check that the 'today' macro was defined" + $t grep -q erlang_mk_sphinx_today $(APP)/html/manpage.html + +sphinx-source-dir: build clean + + $i "Bootstrap a new OTP application named $(APP)" + $t mkdir $(APP)/ + $t cp ../erlang.mk $(APP)/ + $t $(MAKE) -C $(APP) -f erlang.mk bootstrap $v + + $i "Change documentation source directory" + $t echo "SPHINX_SOURCE = documentation" >> $(APP)/Makefile + + $i "Generate Sphinx config" + $(call sphinx-generate-doc-skeleton,documentation) + + $i "Run Sphinx (html)" + $t $(MAKE) -C $(APP) sphinx $v + + $i "Check that documentation was generated" + $t test -f $(APP)/html/index.html + $t test -f $(APP)/html/manpage.html + +sphinx-formats: build clean + + $i "Bootstrap a new OTP application named $(APP)" + $t mkdir $(APP)/ + $t cp ../erlang.mk $(APP)/ + $t $(MAKE) -C $(APP) -f erlang.mk bootstrap $v + + $i "Define formats generated by Sphinx" + $t echo "SPHINX_FORMATS = html man" >> $(APP)/Makefile + + $i "Generate Sphinx config" + $(call sphinx-generate-doc-skeleton) + + $i "Run Sphinx (html + man)" + $t $(MAKE) -C $(APP) sphinx $v + + $i "Check that documentation was generated" + $t test -f $(APP)/man/sphinx_$(APP).1 + $t test -f $(APP)/html/index.html + $t test -f $(APP)/html/manpage.html + + $i "Distclean the application" + $t $(MAKE) -C $(APP) distclean $v + + $i "Check that the generated documentation was removed" + $t test ! -e $(APP)/man/sphinx_$(APP).1 + $t test ! -e $(APP)/html/index.html + $t test ! -e $(APP)/html/manpage.html + + $i "Change documentation output directories" + $t echo "sphinx_html_output = sphinx/html_output" >> $(APP)/Makefile + $t echo "sphinx_man_output = sphinx/man_output" >> $(APP)/Makefile + + $i "Run Sphinx (html + man)" + $t $(MAKE) -C $(APP) sphinx $v + + $i "Check that documentation was generated" + $t test -f $(APP)/sphinx/man_output/sphinx_$(APP).1 + $t test -f $(APP)/sphinx/html_output/index.html + $t test -f $(APP)/sphinx/html_output/manpage.html + + $i "Distclean the application" + $t $(MAKE) -C $(APP) distclean $v + + $i "Check that the generated documentation was removed" + $t test ! -e $(APP)/sphinx/man_output/sphinx_$(APP).1 + $t test ! -e $(APP)/sphinx/html_output/index.html + $t test ! -e $(APP)/sphinx/html_output/manpage.html + +sphinx-format-opts: build clean + + $i "Bootstrap a new OTP application named $(APP)" + $t mkdir $(APP)/ + $t cp ../erlang.mk $(APP)/ + $t $(MAKE) -C $(APP) -f erlang.mk bootstrap $v + + $i "Define formats generated by Sphinx" + $t echo "SPHINX_FORMATS = html man" >> $(APP)/Makefile + + $i "Change format-specific options" + $t echo "sphinx_html_opts = -D 'today=erlang_mk_sphinx_html_today'" >> $(APP)/Makefile + $t echo "sphinx_man_opts = -D 'today=erlang_mk_sphinx_man_today'" >> $(APP)/Makefile + + $i "Generate Sphinx config" + $(call sphinx-generate-doc-skeleton) + + $i "Run Sphinx (html + man)" + $t $(MAKE) -C $(APP) sphinx $v + + $i "Check that the 'today' macro was defined correctly" + $t grep -q erlang_mk_sphinx_html_today $(APP)/html/manpage.html + $t grep -q erlang_mk_sphinx_man_today $(APP)/man/sphinx_$(APP).1 + + +define sphinx-generate-doc-skeleton +$t mkdir $(APP)/$(if $1,$1,doc)/ +$t printf "%s\n" \ + "project = '$(APP)'" \ + "master_doc = 'index'" \ + "source_suffix = '.rst'" \ + "man_pages = [('manpage', 'sphinx_$(APP)', 'Man Page', [], 1)]" \ + "" > $(APP)/$(if $1,$1,doc)/conf.py + +$t printf "%s\n" \ + "***********" \ + "Sphinx Docs" \ + "***********" \ + "" \ + "ToC" \ + "===" \ + "" \ + ".. toctree::" \ + "" \ + " manpage" \ + "" \ + "Indices" \ + "=======" \ + "" \ + '* :ref:`genindex`' \ + '* :ref:`modindex`' \ + '* :ref:`search`' \ + "" > $(APP)/$(if $1,$1,doc)/index.rst + +$t printf "%s\n" \ + "********" \ + "Man Page" \ + "********" \ + "" \ + "Synopsis" \ + "========" \ + "" \ + ".. code-block:: none" \ + "" \ + " erlang-sphinx-mk-man [--help]" \ + "" \ + "today = |today|" \ + "" > $(APP)/$(if $1,$1,doc)/manpage.rst +endef -- cgit v1.2.3