libopencm3/doc

libopencm3 Documentation
14 September 2012 (C) K Sarkies
------------------------

To generate documentation run 'make doc' in the doc directory. This
runs doxygen for each of the processor families then integrates the whole.

This requires doxygen v 1.8.2 or later.

HTML, LaTeX, and pdf output is produced.

Generation of HTML
------------------

To view HTML, point a browser to doc/html/index.html.

The directory structure is important and should be maintained.
Each of the subdirectories has a configuration file, a layout file and
subdirectories for the documentation. Doxygen is intended to be run inside
these subdirectories. The Makefile will handle this in the appropriate
order. Tag files are generated and used by other doxygen runs to resolve links.

Tagfiles contain all information about the document, and are used to resolve
references in other documents. The groups defined in these external documents
are not shown when EXTERNAL_GROUPS = NO. The high level tagfiles must be generated
before any others.

As well as the processor families, a "cm3" subdirectory is used to generate
a tagfile to integrate the CM3 common core defines.

Doxyfile_common holds global settings.

OUTPUT_DIRECTORY blank so that the output is placed in the current directory.
RECURSIVE = NO
EXTERNAL_GROUPS = NO

Each Doxyfile_include for a processor family has:

@INCLUDE = ../Doxyfile_common
INPUT = specific directories needed, including /include/libopencm3/cm3
		in top directory to set the top level page and GNU license.
LAYOUT_FILE = DoxygenLayout_$processor.xml
WARN_LOGFILE = doxygen_$processor.log
TAGFILES = ../cm3/cm3.tag=../../cm3/html
GENERATE_TAGFILE = $processor.tag

For the STM32 subfamilies, to include the common files references, add
TAGFILES += ../stm32/stm32.tag=../../stm32/html

For the top level Doxyfile

INPUT = ../include/libopencm3/docmain.dox to add in the main page text
LAYOUT_FILE = DoxygenLayout.xml
WARN_LOGFILE = doxygen.log
TAGFILES = cm3/cm3.tag=../cm3/html plus all families to be included.

Generation of PDF
-----------------

The pdf is generated via LaTeX. The needs for the documents differ from HTML
so separate Doxyfile_latex are provided. The pdf files are placed in the
doc directory. Each file contains all documentation for the core and common
features.

@INCLUDE = ../Doxyfile_common
GENERATE_LATEX = YES
GENERATE_HTML = NO