In this tutorial we will learn how to create automatically built documentation for a custom plugin. We use doxygen for this purpose and assume that you already made yourself familiar to it.
OpenFlipper provides its documentation and API references in two different forms:
doxygen they can be found under the OpenFlipper/Docs directory in OpenFlipper's root folder). These are basically the same files as one can find on the website.Help in OpenFlipper's menu bar.Now developers have the possibility to deliver their own plugin specific documentation and integrate it into OpenFlipper's help system. Generating compressed qt help files is supported by doxygen since version 1.5.7, therefore we recommend to use the latest doxygen version in order to build compressed help files out of the documentation that can be integrated into the application's help browser.
In this tutorial we want to create the documentation of our plugin that we have already created in A simple plugin. For this we go into our plugin's directory (here Plugin-SimplePlugin) and create a directory named Doxygen. This is the directory that will contain all the necessary docu-files. In this case we only create one mainpage with some arbitrary content (refer to doxygen documentation in order to learn more about doxygen).
Now copy the file Doxyfile.dox (which can be found in OpenFlipper/Doxygen/Developer/example) into your plugin's directory and name it Doxyfile. Adapt the following project specific settings in the Doxyfile:
PROJECT_NAME = SimplePlugin
PROJECT_NUMBER = 1.0
QHP_NAMESPACE = "org.openflipper.plugin-simpleplugin"
QCH_FILE = simpleplugin-doc.qch
DOCSET_FEEDNAME = "SimplePlugin 1.0 Help"
DOCSET_BUNDLE_ID = org.openflipper.plugin-simpleplugin
IMPORTANT: For your documentation to integrate seamlessly into OpenFlipper's help system you have to leave the QHP_VIRTUAL_FOLDER untouched! Further QCH_NAMESPACE has to be unique, particularly the namespaces "org.openflipper.dev" and "org.openflipper.user" are reserved.
The last thing to be done is adding Doc(Plugin-SimplPlugin) to your qmake project file. This adds the target doc to the build system which builds the plugin's documentation.
IMPORTANT: The argument passed to the Doc() function indicates the name of the documentation's subfolder that will be created by the build system. The name passed here has to match the one specified at the end of the QHP_NAMESPACE (they are not considered case-sensitive). If both names are not equal, cross-referencing won't work in OpenFlipper's help browser.
include( $$TOPDIR/qmake/all.include ) Plugin() Doc(Plugin-SimplePlugin) DIRECTORIES = .
After executing qmake (make sure to use qmake version >= 4, some linux distributions offer the symlink qmake-qt4) you just have to enter
make doc
to generate the documentation.
All the files will be created in the folder Doc/html in your plugin's directory. You can now open the index.html to see it. When using doxygen >= 1.5.7 an additional .qch file (the filename can be specified in the Doxyfile) has been generated and copied to OpenFlipper/Help/ in OpenFlipper's root directory. To integrate it into OpenFlipper's help browser go to OpenFlipper/Help/ and open Help.qhcp in a text editor. Now add the line
<file>plugin-doctest.qch</file>
under the register tag (note: plugin-doctest.qch has to be replaced with whatever filename you have chosen before). The file now should look like this:
<?xml version="1.0" encoding="utf-8" ?> <QHelpCollectionProject version="1.0"> <docFiles> <register> <file>developer.qch</file> <file>simpleplugin-doc.qch</file> </register> </docFiles> </QHelpCollectionProject>
Now (still in OpenFlipper/Help/) execute
qcollectiongenerator Help.qhcp -o Help.qhc
Your documentation should now be available in OpenFlipper's help browser.
This is the full Doxyfile.dox template file that we use to generate the plugin's documentation. You can either find it in OpenFlipper/Doxygen/Developer/example or just copy and paste it.
# Doxyfile 1.5.6 #--------------------------------------------------------------------------- # Project related configuration options #--------------------------------------------------------------------------- DOXYFILE_ENCODING = UTF-8 PROJECT_NAME = SimplePlugin PROJECT_NUMBER = 1.0 OUTPUT_DIRECTORY = ./Docs CREATE_SUBDIRS = NO OUTPUT_LANGUAGE = English BRIEF_MEMBER_DESC = YES REPEAT_BRIEF = YES ABBREVIATE_BRIEF = "The $name class " \ "The $name widget " \ "The $name file " \ is \ provides \ specifies \ contains \ represents \ a \ an \ the ALWAYS_DETAILED_SEC = NO INLINE_INHERITED_MEMB = NO FULL_PATH_NAMES = YES STRIP_FROM_PATH = STRIP_FROM_INC_PATH = GENERATE_QHP = YES QHP_NAMESPACE = "org.openflipper.plugin-simpleplugin" QHP_VIRTUAL_FOLDER = "doc" QCH_FILE = simpleplugin-doc.qch QHG_LOCATION = qhelpgenerator SHORT_NAMES = NO JAVADOC_AUTOBRIEF = NO QT_AUTOBRIEF = NO MULTILINE_CPP_IS_BRIEF = NO DETAILS_AT_TOP = NO INHERIT_DOCS = YES SEPARATE_MEMBER_PAGES = NO TAB_SIZE = 8 ALIASES = OPTIMIZE_OUTPUT_FOR_C = NO OPTIMIZE_OUTPUT_JAVA = NO OPTIMIZE_FOR_FORTRAN = NO OPTIMIZE_OUTPUT_VHDL = NO BUILTIN_STL_SUPPORT = NO CPP_CLI_SUPPORT = NO SIP_SUPPORT = NO IDL_PROPERTY_SUPPORT = YES DISTRIBUTE_GROUP_DOC = NO SUBGROUPING = YES TYPEDEF_HIDES_STRUCT = NO #--------------------------------------------------------------------------- # Build related configuration options #--------------------------------------------------------------------------- EXTRACT_ALL = NO EXTRACT_PRIVATE = YES EXTRACT_STATIC = YES EXTRACT_LOCAL_CLASSES = YES EXTRACT_LOCAL_METHODS = NO EXTRACT_ANON_NSPACES = NO HIDE_UNDOC_MEMBERS = NO HIDE_UNDOC_CLASSES = NO HIDE_FRIEND_COMPOUNDS = NO HIDE_IN_BODY_DOCS = NO INTERNAL_DOCS = NO CASE_SENSE_NAMES = YES HIDE_SCOPE_NAMES = NO SHOW_INCLUDE_FILES = YES INLINE_INFO = YES SORT_MEMBER_DOCS = YES SORT_BRIEF_DOCS = NO SORT_GROUP_NAMES = NO SORT_BY_SCOPE_NAME = NO GENERATE_TODOLIST = YES GENERATE_TESTLIST = YES GENERATE_BUGLIST = YES GENERATE_DEPRECATEDLIST= YES ENABLED_SECTIONS = MAX_INITIALIZER_LINES = 30 SHOW_USED_FILES = YES SHOW_DIRECTORIES = YES SHOW_FILES = YES SHOW_NAMESPACES = YES FILE_VERSION_FILTER = #--------------------------------------------------------------------------- # configuration options related to warning and progress messages #--------------------------------------------------------------------------- QUIET = NO WARNINGS = YES WARN_IF_UNDOCUMENTED = YES WARN_IF_DOC_ERROR = YES WARN_NO_PARAMDOC = NO WARN_FORMAT = "$file:$line: $text " WARN_LOGFILE = #--------------------------------------------------------------------------- # configuration options related to the input files #--------------------------------------------------------------------------- INPUT = . INPUT_ENCODING = UTF-8 FILE_PATTERNS = *.c \ *.cc \ *.cxx \ *.cpp \ *.c++ \ *.java \ *.ii \ *.ixx \ *.ipp \ *.i++ \ *.inl \ *.h \ *.hh \ *.hxx \ *.hpp \ *.h++ \ *.idl \ *.odl \ *.cs \ *.php \ *.php3 \ *.inc \ *.m \ *.mm \ *.dox \ *.C \ *.CC \ *.C++ \ *.II \ *.I++ \ *.H \ *.HH \ *.H++ \ *.CS \ *.PHP \ *.PHP3 \ *.M \ *.MM \ *.C \ *.H \ *.tlh \ *.diff \ *.patch \ *.moc \ *.xpm \ *.docu RECURSIVE = YES EXCLUDE = EXCLUDE_SYMLINKS = NO EXCLUDE_PATTERNS = */Debian*/* \ */.svn/* \ SimpleOpt* EXCLUDE_SYMBOLS = EXAMPLE_PATH = ./Doxygen/example/ EXAMPLE_PATTERNS = * EXAMPLE_RECURSIVE = NO IMAGE_PATH = ./Doxygen/pics/ \ ./Doxygen/screenshots/ INPUT_FILTER = FILTER_PATTERNS = FILTER_SOURCE_FILES = NO #--------------------------------------------------------------------------- # configuration options related to source browsing #--------------------------------------------------------------------------- SOURCE_BROWSER = YES INLINE_SOURCES = NO STRIP_CODE_COMMENTS = YES REFERENCED_BY_RELATION = YES REFERENCES_RELATION = YES REFERENCES_LINK_SOURCE = YES USE_HTAGS = NO VERBATIM_HEADERS = YES #--------------------------------------------------------------------------- # configuration options related to the alphabetical class index #--------------------------------------------------------------------------- ALPHABETICAL_INDEX = YES COLS_IN_ALPHA_INDEX = 5 IGNORE_PREFIX = #--------------------------------------------------------------------------- # configuration options related to the HTML output #--------------------------------------------------------------------------- GENERATE_HTML = YES HTML_OUTPUT = html HTML_FILE_EXTENSION = .html HTML_HEADER = HTML_FOOTER = HTML_STYLESHEET = HTML_ALIGN_MEMBERS = YES GENERATE_HTMLHELP = YES GENERATE_DOCSET = NO DOCSET_FEEDNAME = "SimplePlugin 1.0 Help" DOCSET_BUNDLE_ID = org.openflipper.plugin-simpleplugin HTML_DYNAMIC_SECTIONS = NO CHM_FILE = HHC_LOCATION = GENERATE_CHI = NO CHM_INDEX_ENCODING = BINARY_TOC = NO TOC_EXPAND = NO DISABLE_INDEX = YES ENUM_VALUES_PER_LINE = 4 GENERATE_TREEVIEW = YES TREEVIEW_WIDTH = 250 FORMULA_FONTSIZE = 10 #--------------------------------------------------------------------------- # configuration options related to the LaTeX output #--------------------------------------------------------------------------- GENERATE_LATEX = NO LATEX_OUTPUT = latex LATEX_CMD_NAME = latex MAKEINDEX_CMD_NAME = makeindex COMPACT_LATEX = NO PAPER_TYPE = a4wide EXTRA_PACKAGES = LATEX_HEADER = PDF_HYPERLINKS = NO USE_PDFLATEX = NO LATEX_BATCHMODE = NO LATEX_HIDE_INDICES = NO #--------------------------------------------------------------------------- # configuration options related to the RTF output #--------------------------------------------------------------------------- GENERATE_RTF = NO RTF_OUTPUT = rtf COMPACT_RTF = NO RTF_HYPERLINKS = NO RTF_STYLESHEET_FILE = RTF_EXTENSIONS_FILE = #--------------------------------------------------------------------------- # configuration options related to the man page output #--------------------------------------------------------------------------- GENERATE_MAN = NO MAN_OUTPUT = man MAN_EXTENSION = .3 MAN_LINKS = NO #--------------------------------------------------------------------------- # configuration options related to the XML output #--------------------------------------------------------------------------- GENERATE_XML = NO XML_OUTPUT = xml XML_SCHEMA = XML_DTD = XML_PROGRAMLISTING = YES #--------------------------------------------------------------------------- # configuration options for the AutoGen Definitions output #--------------------------------------------------------------------------- GENERATE_AUTOGEN_DEF = NO #--------------------------------------------------------------------------- # configuration options related to the Perl module output #--------------------------------------------------------------------------- GENERATE_PERLMOD = NO PERLMOD_LATEX = NO PERLMOD_PRETTY = YES PERLMOD_MAKEVAR_PREFIX = #--------------------------------------------------------------------------- # Configuration options related to the preprocessor #--------------------------------------------------------------------------- ENABLE_PREPROCESSING = YES MACRO_EXPANSION = NO EXPAND_ONLY_PREDEF = NO SEARCH_INCLUDES = YES INCLUDE_PATH = INCLUDE_FILE_PATTERNS = PREDEFINED = EXPAND_AS_DEFINED = SKIP_FUNCTION_MACROS = YES #--------------------------------------------------------------------------- # Configuration::additions related to external references #--------------------------------------------------------------------------- TAGFILES = GENERATE_TAGFILE = Subdivision.tag ALLEXTERNALS = NO EXTERNAL_GROUPS = YES PERL_PATH = /usr/bin/perl #--------------------------------------------------------------------------- # Configuration options related to the dot tool #--------------------------------------------------------------------------- CLASS_DIAGRAMS = YES MSCGEN_PATH = HIDE_UNDOC_RELATIONS = YES HAVE_DOT = YES DOT_FONTNAME = FreeSans DOT_FONTPATH = CLASS_GRAPH = YES COLLABORATION_GRAPH = YES GROUP_GRAPHS = YES UML_LOOK = NO TEMPLATE_RELATIONS = YES INCLUDE_GRAPH = YES INCLUDED_BY_GRAPH = YES CALL_GRAPH = NO CALLER_GRAPH = NO GRAPHICAL_HIERARCHY = YES DIRECTORY_GRAPH = YES DOT_IMAGE_FORMAT = png DOT_PATH = DOTFILE_DIRS = DOT_GRAPH_MAX_NODES = 50 MAX_DOT_GRAPH_DEPTH = 0 DOT_TRANSPARENT = NO DOT_MULTI_TARGETS = YES GENERATE_LEGEND = YES DOT_CLEANUP = YES #--------------------------------------------------------------------------- # Configuration::additions related to the search engine #--------------------------------------------------------------------------- SEARCHENGINE = NO
Project OpenFlipper,
© Computer Graphics Group, RWTH Aachen.
Documentation generated using
doxygen
.