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:

bootstrap  

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

$ mkdoc --bootstrap c

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 section.

class_inheritance_bymodule  

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.

code_path  

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 section.

conf_file  

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

cpp_cond_policy  

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

See also Conditional directives section.

cpp_eval_const  

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 section.

cpp_eval_hidden  

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 section and show_undoc_macros section.

debug_cpp  

Specify C preprocessor debug messages level, default is 0.

debug_cxx_parser  

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

doc_author  

Set document author

doc_date  

Set document date

doc_format  

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 section.

doc_logo

Set document logo image file

doc_logo_size  

Resize title logo to XxY resolution

doc_path  

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

See also image_path section, code_path section, conf_file section and output_path section.

doc_title  

Set document title

doc_subtitle  

Set document subtitle

docbook_article  

Write a docbook article rather than a book document.

dump_ast  

Dump code AST without generating DOM tree.

dump_dom  

Dump DOM tree without writing output.

fully_qualified_links  

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.

function_overloading  

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

hide_experimental  

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

hide_internal  

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.

help  

Display help message and exit

html_css  

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

See also Html output section.

html_css_optimize  

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

See also Html output section.

html_embed_css  

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

See also Html output section.

html_footer_links  

Show links in page footer.

See also Html output section.

html_header_links  

Show links in page header.

See also Html output section.

html_index_columns  

Set number of columns for table formatting of index.

See also Html output section.

html_navlinks  

Show previous, up and next navigation links.

See also Html output section.

html_nestlinks  

Show section path links to current section.

See also Html output section.

html_use_hr  

Use horizontal rulers in generated html document.

See also Html output section.

html_single_js  

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

inherit_doc  

Inherit documentation for virtual functions when no documentation is defined

image_path  

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

See also doc_path section.

include_path  

Add a new include search path

latex_use_chapters  

Use \chapter sectionning commands in latex

latex_use_parts  

Use \part sectionning commands in latex

list_anonymous  

Show anonymous symbols in member lists

listify_tables  

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.

man_section  

Set man page section number, default is 3.

math_res  

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

mkdoclib_create  

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

See also External libraries section.

mkdoclib_url  

Set documentation base URL where generated documentation will be hosted.

See also External libraries section.

multiple_symbol_def  

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 section and Conditional directives section.

multiple_macro_def  

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.

output_filename  

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

output_path  

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

See also doc_path section.

qualified_name_scope  

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.

scoped_macros  

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

single_output_file  

Write all documentation in a single output file.

See also Output formats section.

short_typedefs  

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.

short_typedefs_func  

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.

show_examples_path  

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

show_enum_values  

Show enum values in enum tables for all enums

show_decl_short_desc  

Show short documentation in member list when available.

See also @short and @brief tags section.

show_location_hidden_macro  

Show hidden macro names in declaration location sentences.

See also show_location_hidden_header section.

show_location_hidden_header  

Show hidden header names in declaration location sentences.

See also show_location_hidden_macro section.

show_module_subtitle  

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

show_macro_content  

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  

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

show_private  

Do write documentation for private members. Default is 0.

show_protected  

Do write documentation for protected members. Default is 1.

show_synopsis_scopes  

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

#include <foo.hh>

namespace Foo {
template <typename Key> class Bar;
};

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

#include <foo.hh>

template <typename Key> class Bar;

show_synopsis_default  

Default value of parameters will appear in symbol synopsis.

show_type_keyword  

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

show_undoc_macros  

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.

source_rev  

Set source code revision number.

See also source_url_template section.

source_url_template  

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 section and source_rev section.

strip_search_path  

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

titled_refs  

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.

top_file  

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

warn_undefined_types  

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.

Valid XHTML 1.0 StrictGenerated by diaxen on Sun Jan 8 22:43:00 2012 using MkDoc