8.7 Role-File doc.mk

Use the doc role to create doxygen documentation related to a package or to compile latex files.

8.7.1 Doxygen support

The doc role allows to generate multiple documentations using doxygen, e.g. an API documentation, an internal documentation and a documentation of the usage of your server. For each documentation, pick a unique name beginning with the name of the package you are writing the documentation for. Save the doxygen files using these names, with the .cfg extension added. Ensure all configurations build into a subdir with the name of that documentation. List the configuration files within the SRC_DOX_* variables. A make all will create the documentation and optionally install the html files into $(L4DIR)/doc/html/. With the make-file located in this directory, you can build an index to the documentation of all DROPS packages then.

The dependency mechanism detects all changes in your source files.

Doxygen support allows to group your documentation into one of four groups: user guides, reference manuals, internal documentation and the rest. This classification is used when generating the index page in $(L4DIR)/doc/html/.

8.7.2 Latex support

The doc role provides rules to compile L^ATEX files into .ps and .pdf, and to convert xfig images to eps. List the .tex files you want to be compiled in the SRC_TEX variable. The first file in the $(SRC_TEX) is the primary tex document. The compiled version of the primary tex document is easily showed by calling the "showdvi" or the "showps" target. To rebuild the primary tex document, call "make dvi" or "make ps". A successful compilation triggers a redraw within the appropriate viewer.

8.7.3 Make-Targets

all::

Phony target. Generate documentation and install it locally.

install::

Phony target. Generate documentation and install it globally.

dvi::, ps::, pdf::

Phony targets. Compile the primary tex document into dvi and ps, respectively.

showdvi::, showps::, showpdf::

Phony targets. Invoke a viewer on the compiled version of the primary tex document.

clean::

Delete intermediate compilation files.

cleanall::

Delete all generated files.

8.7.4 Optional Parameters

DOXY_FLAGS+	Semicolon-separated list of additional flags for doxygen. Should be set in Makecond.local to enable/disable warnings and status output. Default: empty. Note: All semicolons are removed, no escaping!
SRC_DOX	List of doxygen configuration files that will be compiled using doxygen. The files should end on .cfg and should build into a directory with the same name and the .cfg removed.
SRC_DOX_GUIDE	As $(SRC_DOX). Documentation will be classified as user guide.
SRC_DOX_INT	As $(SRC_DOX). Documentation will be classified as internal.
SRC_DOX_REF	As $(SRC_DOX). Documentation will be classified as reference manual.
SRC_TEX	List of LATEX files that will be compiled into postscript files.

8.7.5 Example

PKGDIR = ..
L4DIR ?= $(PKGDIR)/../..

SRC_DOX_REF = dm_phys.cfg
include $(L4DIR)/mk/doc.mk