aboutsummaryrefslogtreecommitdiff
path: root/doc/README
diff options
context:
space:
mode:
authorKen Sarkies2012-09-15 12:51:46 +0930
committerKen Sarkies2012-09-15 12:51:46 +0930
commitff83a1ae1c0764aff11d8cd50f1f0f8a27ea4757 (patch)
tree030d15b829c2c76f1b97891a92cfc697d73aed3b /doc/README
parentdcd98dde86c68340e950d12b078d24fd30bef625 (diff)
Setup to document entire project using doxygen.
New doc directory with config files and generated html, LaTeX/pdf. Makefile provided for autogeneration and explanatory README. The project structure is hostile to doxygen, which can't cope with functions of the same name. Doxygen is run for each family separately, and separately for LaTeX generation. Customized layout files sort of "integrate" HTML, and separate pdfs are generated for each family. Not ideal but seems the best solution until doxygen changes, if at all.
Diffstat (limited to 'doc/README')
-rw-r--r--doc/README68
1 files changed, 68 insertions, 0 deletions
diff --git a/doc/README b/doc/README
new file mode 100644
index 0000000..81d8262
--- /dev/null
+++ b/doc/README
@@ -0,0 +1,68 @@
+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
+