I mentionned NaturalDocs in an earlier post on this blog since we're using it to document the Augeas C API and Augeas lenses.
With the latest version of Augeas now out, I wanted to get these docs generated with the package so they could be shipped in an augeas-doc package in Debian and Ubuntu. I first had to fix a missing link in the naturaldocs package (which was also the occasion to upgrade it to 1.5). Then I had to get naturaldocs in main, since augeas is in main already. While going through the MIR, I was asked if other packages in main could benefit from this change. I haven't found any, but there's quite a few packages in universe that could use naturaldocs to generate documentation at build time. The bug report lists some of them.
If you're interested in building NaturalDocs documentation in your package, here is the way it was done for Augeas.
Augeas is a C project using autotools. It was thus easier to activate NaturalDocs as an option in configure. This can easily be adapted for other cases, including running the commands in debian/rules directly.
In configure.ac:
dnl Check for NaturalDocs AC_PATH_PROGS([ND_PROG], [naturaldocs NaturalDocs], missing) AM_CONDITIONAL([ND_ENABLED], [test "x$ND_PROG" != "xmissing"])
dnl NaturalDocs output format, defaults to HTML ND_FORMAT=HTML AC_ARG_WITH([naturaldocs-output], [AS_HELP_STRING([--with-naturaldocs-output=FORMAT], [format of NaturalDocs output (possible values: HTML/FramedHTML, default: HTML)])], [ if test "x$ND_PROG" = "xmissing"; then AC_MSG_ERROR([NaturalDocs was not found on your path; there's no point in setting the output format]) fi case $withval in HTML|FramedHTML) ND_FORMAT=$withval ;; *) AC_MSG_ERROR($withval is not a supported output format for NaturalDocs) ;; esac ]) AC_SUBST(ND_FORMAT)
In doc/naturaldocs/Makefile.am:
EXTRA_DIST = $(wildcard conf/Augeas.css conf/c_api/*.txt) \ $(wildcard conf/lenses/*.txt) \ Modules/NaturalDocs/Languages/Augeas.pm
ND_CONF=$(srcdir)/conf ND_OUTPUT=output ND_STYLE=../Augeas
ND_PERL5LIB=$(abs_srcdir)/Modules ND_PERL5OPT='-MNaturalDocs::Languages::Augeas'
if ND_ENABLED all-local: NaturalDocs endif
NaturalDocs: NDLenses NDCAPI
env: echo LIB $(ND_PERL5LIB) echo OPT $(ND_PERL5OPT) test -n "$$PERL5OPT" && ND_PERL5OPT="$(ND_PERL5OPT) $$PERL5OPT" || ND_PERL5OPT=$(ND_PERL5OPT); \ test -n "$$PERL5LIB" && ND_PERL5LIB="$(ND_PERL5LIB):$$PERL5LIB" || ND_PERL5LIB=$(ND_PERL5LIB); \ PERL5LIB=$$ND_PERL5LIB PERL5OPT=$$ND_PERL5OPT env | grep PERL
NDLenses: NDConf @mkdir -p $(ND_OUTPUT)/lenses @(echo "Format lens documentation"; \ test -n "$$PERL5OPT" && ND_PERL5OPT="$(ND_PERL5OPT) $$PERL5OPT" || ND_PERL5OPT=$(ND_PERL5OPT); \ test -n "$$PERL5LIB" && ND_PERL5LIB="$(ND_PERL5LIB):$$PERL5LIB" || ND_PERL5LIB=$(ND_PERL5LIB); \ PERL5LIB=$$ND_PERL5LIB PERL5OPT=$$ND_PERL5OPT \ $(ND_PROG) -p conf/lenses \ -i $(top_srcdir)/lenses \ -o $(ND_FORMAT) $(ND_OUTPUT)/lenses \ -s $(ND_STYLE))
NDCAPI: NDConf @mkdir -p $(ND_OUTPUT)/c_api @(echo "Format C API documentation"; \ test -n "$$PERL5OPT" && ND_PERL5OPT="$(ND_PERL5OPT) $$PERL5OPT" || ND_PERL5OPT=$(ND_PERL5OPT); \ test -n "$$PERL5LIB" && ND_PERL5LIB="$(ND_PERL5LIB):$$PERL5LIB" || ND_PERL5LIB=$(ND_PERL5LIB); \ $(ND_PROG) -p conf/c_api \ -i $(top_srcdir)/src \ -o $(ND_FORMAT) $(ND_OUTPUT)/c_api \ -s $(ND_STYLE))
NDConf: @(if test ! -d $(ND_CONF); then \ cp -pr $(ND_CONF) conf; \ fi)
clean-local: rm -rf output conf/Data rm -rf $(ND_CONF)/c_api/Data $(ND_CONF)/lenses/Data
After that, the NaturalDocs docs can be built by calling --with-naturaldocs-output=HTML or --with-naturaldocs-output=FramedHTML.
I hope this can be useful to improve the shipped documentation for projects already using NaturalDocs.