aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--doc/src/guide/asciidoc.asciidoc75
-rw-r--r--plugins/asciidoc.mk8
-rw-r--r--test/plugin_asciidoc.mk158
3 files changed, 234 insertions, 7 deletions
diff --git a/doc/src/guide/asciidoc.asciidoc b/doc/src/guide/asciidoc.asciidoc
index 2fca131..621f5b5 100644
--- a/doc/src/guide/asciidoc.asciidoc
+++ b/doc/src/guide/asciidoc.asciidoc
@@ -1,6 +1,75 @@
[[asciidoc]]
-== Asciidoc documentation
+== AsciiDoc documentation
-// @todo Write it.
+Erlang.mk provides rules for generating documentation from
+AsciiDoc files. It can automatically build a user guide PDF,
+chunked HTML documentation and Unix manual pages.
-Placeholder chapter.
+=== Writing AsciiDoc documentation
+
+http://asciidoc.org/[AsciiDoc] is a text document format for
+writing notes, documentation, articles, books, ebooks, slideshows,
+web pages, man pages and blogs. AsciiDoc files can be translated
+to many formats including HTML, PDF, EPUB, man page.
+
+The http://asciidoc.org/userguide.html[AsciiDoc user guide]
+describes the AsciiDoc syntax.
+
+The https://github.com/ninenines/erlang.mk/tree/master/doc/src/guide[Erlang.mk user guide]
+is written in AsciiDoc and can be used as an example. The entry
+file is https://github.com/ninenines/erlang.mk/blob/master/doc/src/guide/book.asciidoc[book.asciidoc].
+
+Erlang.mk expects you to put your documentation in a specific
+location. This is 'doc/src/guide/' for the user guide, and
+'doc/src/manual/' for the function reference. In the case of
+the user guide, the entry point is always 'doc/src/guide/book.asciidoc'.
+
+For manual pages, it is good practice to use section 3 for
+modules, and section 7 for the application itself.
+
+=== Configuration
+
+All of the AsciiDoc related configuration can be done directly
+inside the files themselves.
+
+=== Usage
+
+To build all documentation:
+
+[source,bash]
+$ make docs
+
+To build only the AsciiDoc documentation:
+
+[source,bash]
+$ make asciidoc
+
+To build only the user guide:
+
+[source,bash]
+$ make asciidoc-guide
+
+To build only the manual:
+
+[source,bash]
+$ make asciidoc-manual
+
+To install man pages on Unix:
+
+[source,bash]
+$ make install-docs
+
+Erlang.mk allows customizing the installation path and sections
+of the man pages to be installed. The `MAN_INSTALL_PATH` variable
+defines where man pages will be installed. It defaults to
+'/usr/local/share/man'. The `MAN_SECTIONS` variable defines
+which manual sections are to be installed. It defaults to `3 7`.
+
+To install man pages to a custom location:
+
+[source,bash]
+$ make install-docs MAN_INSTALL_PATH=/opt/share/man
+
+Note that you may need to run the install commands using
+`sudo` or equivalent if the location is not writeable by
+your user.
diff --git a/plugins/asciidoc.mk b/plugins/asciidoc.mk
index baf4d3b..ab7fa4b 100644
--- a/plugins/asciidoc.mk
+++ b/plugins/asciidoc.mk
@@ -8,12 +8,12 @@ MAN_SECTIONS ?= 3 7
docs:: asciidoc
-asciidoc: distclean-asciidoc doc-deps asciidoc-guide asciidoc-manual
+asciidoc: asciidoc-guide asciidoc-manual
ifeq ($(wildcard doc/src/guide/book.asciidoc),)
asciidoc-guide:
else
-asciidoc-guide:
+asciidoc-guide: distclean-asciidoc doc-deps
a2x -v -f pdf doc/src/guide/book.asciidoc && mv doc/src/guide/book.pdf doc/guide.pdf
a2x -v -f chunked doc/src/guide/book.asciidoc && mv doc/src/guide/book.chunked/ doc/html/
endif
@@ -21,7 +21,7 @@ endif
ifeq ($(wildcard doc/src/manual/*.asciidoc),)
asciidoc-manual:
else
-asciidoc-manual:
+asciidoc-manual: distclean-asciidoc doc-deps
for f in doc/src/manual/*.asciidoc ; do \
a2x -v -f manpage $$f ; \
done
@@ -36,7 +36,7 @@ install-docs:: install-asciidoc
install-asciidoc: asciidoc-manual
for s in $(MAN_SECTIONS); do \
mkdir -p $(MAN_INSTALL_PATH)/man$$s/ ; \
- install -g 0 -o 0 -m 0644 doc/man$$s/*.gz $(MAN_INSTALL_PATH)/man$$s/ ; \
+ install -g `id -u` -o `id -g` -m 0644 doc/man$$s/*.gz $(MAN_INSTALL_PATH)/man$$s/ ; \
done
endif
diff --git a/test/plugin_asciidoc.mk b/test/plugin_asciidoc.mk
new file mode 100644
index 0000000..a583585
--- /dev/null
+++ b/test/plugin_asciidoc.mk
@@ -0,0 +1,158 @@
+# AsciiDoc plugin.
+
+ASCIIDOC_CASES = build docs guide install manual
+ASCIIDOC_TARGETS = $(addprefix asciidoc-,$(ASCIIDOC_CASES))
+
+.PHONY: asciidoc $(ASCIIDOC_TARGETS)
+
+asciidoc: $(ASCIIDOC_TARGETS)
+
+asciidoc-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 "Only enable man pages section 3"
+ $t perl -ni.bak -e 'print;if ($$.==1) {print "MAN_SECTIONS = 3\n"}' $(APP)/Makefile
+
+ $i "Run AsciiDoc"
+ $t $(MAKE) -C $(APP) asciidoc $v
+
+ $i "Check that no documentation was generated"
+ $t test ! -e $(APP)/doc/guide.pdf
+ $t test ! -e $(APP)/doc/html/
+ $t test ! -e $(APP)/doc/man3/
+
+ $i "Generate AsciiDoc documentation"
+ $t mkdir -p $(APP)/doc/src/guide/ $(APP)/doc/src/manual/
+ $t printf "%s\n" \
+ "= Erlang.mk tests" "" \
+ "Hello world!" > $(APP)/doc/src/guide/book.asciidoc
+ $t printf "%s\n" \
+ "= erlang_mk(3)" "" \
+ "== Name" "" \
+ "erlang_mk - Erlang.mk test" "" \
+ "== Description" "" \
+ "Hello world!" > $(APP)/doc/src/manual/erlang_mk.asciidoc
+
+ $i "Run AsciiDoc"
+ $t $(MAKE) -C $(APP) asciidoc $v
+
+ $i "Check that the documentation was generated"
+ $t test -f $(APP)/doc/guide.pdf
+ $t test -d $(APP)/doc/html/
+ $t test -f $(APP)/doc/man3/erlang_mk.3.gz
+
+ $i "Distclean the application"
+ $t $(MAKE) -C $(APP) distclean $v
+
+ $i "Check that the generated documentation was removed"
+ $t test ! -e $(APP)/doc/guide.pdf
+ $t test ! -e $(APP)/doc/html/
+ $t test ! -e $(APP)/doc/man3/
+
+ $i "Generate an invalid AsciiDoc file"
+ $t printf "%s\n" \
+ "= fail(3)" "" \
+ "This will fail because the Name section is missing." > $(APP)/doc/src/manual/fail.asciidoc
+
+ $i "Check that AsciiDoc errors out"
+ $t ! $(MAKE) -C $(APP) asciidoc $v
+
+asciidoc-docs: 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 AsciiDoc documentation"
+ $t mkdir -p $(APP)/doc/src/guide/
+ $t printf "%s\n" \
+ "= Erlang.mk tests" "" \
+ "Hello world!" > $(APP)/doc/src/guide/book.asciidoc
+
+ $i "Check that AsciiDoc runs on 'make docs'"
+ $t $(MAKE) -C $(APP) docs $v
+ $t test -f $(APP)/doc/guide.pdf
+ $t test -d $(APP)/doc/html/
+
+asciidoc-guide: 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 AsciiDoc documentation"
+ $t mkdir -p $(APP)/doc/src/guide/ $(APP)/doc/src/manual/
+ $t printf "%s\n" \
+ "= Erlang.mk tests" "" \
+ "Hello world!" > $(APP)/doc/src/guide/book.asciidoc
+ $t printf "%s\n" \
+ "= erlang_mk(3)" "" \
+ "== Name" "" \
+ "erlang_mk - Erlang.mk test" "" \
+ "== Description" "" \
+ "Hello world!" > $(APP)/doc/src/manual/erlang_mk.asciidoc
+
+ $i "Check that only the guide is generated on 'make asciidoc-guide'"
+ $t $(MAKE) -C $(APP) asciidoc-guide $v
+ $t test -f $(APP)/doc/guide.pdf
+ $t test -d $(APP)/doc/html/
+ $t test ! -e $(APP)/doc/man3/
+
+asciidoc-install: 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 "Only enable man pages section 3"
+ $t perl -ni.bak -e 'print;if ($$.==1) {print "MAN_SECTIONS = 3\n"}' $(APP)/Makefile
+
+ $i "Generate AsciiDoc documentation"
+ $t mkdir -p $(APP)/doc/src/manual/
+ $t printf "%s\n" \
+ "= erlang_mk(3)" "" \
+ "== Name" "" \
+ "erlang_mk - Erlang.mk test" "" \
+ "== Description" "" \
+ "Hello world!" > $(APP)/doc/src/manual/erlang_mk.asciidoc
+
+ $i "Build and install the man pages to $(APP)/installed/"
+ $t $(MAKE) -C $(APP) install-docs MAN_INSTALL_PATH=installed/share $v
+
+ $i "Check that the documentation was installed properly"
+ $t test -f $(APP)/installed/share/man3/erlang_mk.3.gz
+
+asciidoc-manual: 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 "Only enable man pages section 3"
+ $t perl -ni.bak -e 'print;if ($$.==1) {print "MAN_SECTIONS = 3\n"}' $(APP)/Makefile
+
+ $i "Generate AsciiDoc documentation"
+ $t mkdir -p $(APP)/doc/src/guide/ $(APP)/doc/src/manual/
+ $t printf "%s\n" \
+ "= Erlang.mk tests" "" \
+ "Hello world!" > $(APP)/doc/src/guide/book.asciidoc
+ $t printf "%s\n" \
+ "= erlang_mk(3)" "" \
+ "== Name" "" \
+ "erlang_mk - Erlang.mk test" "" \
+ "== Description" "" \
+ "Hello world!" > $(APP)/doc/src/manual/erlang_mk.asciidoc
+
+ $i "Check that only the manual is generated on 'make asciidoc-manual'"
+ $t $(MAKE) -C $(APP) asciidoc-manual $v
+ $t test ! -e $(APP)/doc/guide.pdf
+ $t test ! -e $(APP)/doc/html/
+ $t test -f $(APP)/doc/man3/erlang_mk.3.gz