diff options
| -rw-r--r-- | doc/src/guide/asciidoc.asciidoc | 75 | ||||
| -rw-r--r-- | plugins/asciidoc.mk | 8 | ||||
| -rw-r--r-- | test/plugin_asciidoc.mk | 158 |
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 |