7 Configuration options

Configuration options can be set on the command line or from the optional conf.mkdoc file found in the documentation directory using the @setopt tag. When passed from the command line, option names must begin with two hyphen characters (-- ). Underscore and hyphen characters can be used indifferently in option names.

The following options are available:

This option instructs mkdoc to create a documentation directory and to copy initial documentation files:

Several initial documentation profiles are available:

• c : Manual for C project

• cxx : Manual for C++ project

• cman : Manpages for C project

• plain : Plain documentation only

See also Quick start.

When this option is enabled, derived classes lists and inheritance trees only shows derived classes which belong to the same module as the documented class.

Specify the directory were source files are located. This path used by the @example tag and to check valid source file names to highlight. Default is the current directory.

See also doc_path.

Set configuration file name relative to doc_path. default is mkdoc.conf.

This option control the default preprocessor behavior when encountering conditional directives. The default value is take.

See also Conditional directives.

When enables, this option instructs the preprocessor to use the eval_top behavior for conditional expressions which doesn't involve a macro.

This allows skipping code inside #if 0 conditional blocks.

Default is enabled.

See also Conditional directives.

When enabled, this option instructs the preprocessor to use the eval behavior when a preprocessor condition involves only hidden macros.

Default is disabled.

See also Conditional directives and show_undoc_macros.

Specify C preprocessor debug messages level, default is 0.

Specify C/C++ parser debug messages level, default is 0.

Set document author

Set document date

Set documentation output format (html, latex, texinfo, text, man, rst, docbook, rtf). A comma separated list of output formats may be sepcified.

See also Output formats.

Set document logo image file

Resize title logo to XxY resolution

Directory which contains documentation source files. The default value is "./doc".

See also image_path, code_path, conf_file and output_path.

Set document title

Set document subtitle

Write a docbook article rather than a book document.

Dump code AST without generating DOM tree.

Dump DOM tree without writing output.

Use a link for each element of fully qualified names. Default is to use a link for last part only and use normal text for scope part.

Use function parameters along with name as signature. This is the default behavior and should be used for C++ code.

Do not write documentation for symbols marked as @experimental tag.

Do not write documentation for symbols marked as @internal tag.

Documentation content can be put inside conditional sections which depend on this option value by using the @ifopt and @ifnopt tags.

Display help message and exit

Copy specified style sheet to html output. Available names are: default, website, lightgray, qt46like, rounded, snow and datasheet .

See also Html output.

Parse CSS file to skip useless span/div tags in HTML output.

See also Html output.

Embed CSS file into generated html output. Usefull for use with html_single_js and single_output_file.

See also Html output.

Show links in page footer.

See also Html output.

Show links in page header.

See also Html output.

Set number of columns for table formatting of index.

See also Html output.

Show previous, up and next navigation links.

See also Html output.

Show section path links to current section.

See also Html output.

Use horizontal rulers in generated html document.

See also Html output.

Embed the whole document in a single html file and use javascript for navigation so that only one page section is displayed at once.

Embed a table of content on the side of all html pages.

Inherit documentation for virtual functions when no documentation is defined

Specify the search path used by the @image tag. The default value is "./doc".

See also doc_path.

Add a new include search path

Use \chapter sectionning commands in latex

Use \part sectionning commands in latex

Show anonymous symbols in member lists

Transform some simple tables in lists in DOM tree, this apply to generated table of all classes, modules... and to struct and enum description tables.

Set man page section number, default is 3.

Set resolution of mathematical formula images generated by the @math tag.

Set maximum length for output file names, default is 80.

Export a mkdoclib file to reference generated documentation from other project manuals.

See also External libraries.

Set documentation base URL where generated documentation will be hosted.

See also External libraries.

When enabled, each declaration is treated as a new one even if a symbol with the same name has already been declared before.

This following behaviour is expected:

• Repeated declaration will appear multiple times in the documentation.

• No complain will be emitted if a different symbol with the same name as already been declared.

See also multiple_macro_def and Conditional directives.

When enabled, each redefinition of a macro will generate a new entry in the documentation.

The multiple_symbol_def option is similar for C/C++ symbols.

Set bare name of the output file. Default is "doc".

Directory where output documentation is written. The default value is "doc/".

See also doc_path.

Mark as internal all symbols inside an internal scope. This is not enabled for C++ by default because an internal base class may contain non-internal members which must appear in the documentation of derived classes.

Set scope used for output of qualified symbol names.

Default is to use shortest qualified name to reach the symbol from the current documentation scope. For instance a type foo_t declared in the A::B namespace will be refered to as B::foo_t when used in documentation of the A::C namespace.

This is sometime useful to set this option to the name of namespace used by the whole C++ library. An other option is to use the @scope tag.

When this option is set to global scope (denoted by :: value), all identifiers will appear fully qualified in the documentation.

Attach macro to current C++ scope instead of global scope. This allow display of macros as namespace and class members in the documentation.

Write all documentation in a single output file.

See also Output formats.

Shorten typedefs in members list by hiding existing type expression. Type expression is replaced with elipsis.

The short_typedefs_func option is available for functions typedefs.

The @showvalue tag can be used to override this behavior for a single declaration.

Shorten function typedefs in members list by hiding existing type expression. Type expression is replaced with elipsis.

The @showvalue tag can be used to override this behavior for a single declaration.

Add a code comment with path to included examples code file when using the @example tag.

Show enum values in enum tables for all enums

Show short documentation in member list when available.

See also @short and @brief tags.

Show hidden macro names in declaration location sentences.

See also show_location_hidden_header.

Show hidden header names in declaration location sentences.

See also show_location_hidden_macro.

Show module name subtitle on symbol documentation section with P flag set.

Enable display of macro content in macro documentation sections. This can be enforced on a per macro basis with the @showcontent tag or @showvalue tag.

Macros with short alphanumerical content will retain the @showvalue tag behavior and other macros will use the @showcontent tag behavior.

Show inaccessible inherited members in full members lists. Default is 0.

Do write documentation for private members. Default is 0.

Do write documentation for protected members. Default is 1.

Symbol synopsis will include nesting namespaces and classes when this option is set:

When this option is disabled, the synopsis will look like this:

Default value of parameters will appear in symbol synopsis.

Show class,struct,... type keyword before each type names

Do not hide preprocessor marcos which have no associated documentation text content.

The default behavior is to hide undocumented macros. Undocumented macros can still be made visible when this option is enable by using the @visible tag.

Set source code revision number.

See also source_url_template and source_vcs.

Set template url to online source code. @f, @n and @r are replaced by file name, line number and revision. This option allows MkDoc to insert links in the documentation to an online version of the source code files.

See also @sourcelink tag and source_rev.

Set the list of vcs tools to use when trying to automatically guess the source revision. The default value is hg,git,svn.

Do not include search path in header file names, default is 1.

Use section titles to compute internal references and file names when writing documentation. When disabled MkDoc uses numbered references for file names (node1.html#ref5, node2.html#ref18, ...). This gives shorter file names but may not yield stable url to the section association when the documentation is modified.

Set documentation top file name relative to doc_path. default is top.mkdoc.

Emit warnings when encountering unknown C types. These warnings are useful to track missing headers or external definitions files. This option is enabled by default.