Configuring Doxide

The doxide.yaml configuration file supports the following entries.

• title

  Main page title. Overruled by command-line option --title.

• description

  Main page description. Overruled by command-line option --description.

• style (default mkdocs)

  Style of Markdown output. Overruled by command-line option --style. Supported styles are:

  • mkdocs

    Tailored for use with MkDocs, especially the Material for MkDocs theme. Uses icons and admonitions to highlight code entities.

  • pandoc

    Tailored for use with Pandoc. Uses the fenced_divs extension to highlight code entities and permit custom styling. For best results, set the input format of pandoc (the --from command-line option) to at least markdown+pipe_tables+definition_lists.

  • plain

    A simple style for maximum compatibility. Uses blockquotes to highlight code entities and eschews definition lists, too.

  This site uses the pandoc style. The mkdocs style is the default for legacy reasons, being the original style used by Doxide.

• output (default docs)

  Output directory. Overruled by command-line option --output.

• coverage

  Name of a .gcov or .json file with code coverage data from which to construct a code coverage report, if desired.

• files

  List of source files from which to extract documentation. The following wildcards are supported for pattern matching:

  Pattern	Description
  ?	Any single character.
  *	Zero or more characters, without directory recursion.
  **	Zero or more characters, with directory recursion.
  []	Any characters between the square brackets.
  [!]	Any characters not between the square brackets.
  [a-z]	Any characters in the range a to z.

  For example, *.hpp will match all files in the root directory with a file extension of .hpp, while **/*.hpp will match all files in subdirectories, recursively, with a file extension of .hpp.

• groups

  List of groups used to organize documentation. Each element of the list can further contain the keys:

  • name

    Name of the group. This is used to assign entities to the group using the @ingroup command.

  • title

    Title of the group, used for display purposes.

  • description

    Description of the group, used for display purposes.

  • groups

    Further subgroups, following the same schema.

• defines

  Mapping of preprocessor symbol definitions, where keys are the symbols and values are their replacements. This may be used to troubleshoot parsing issues related to the use of preprocessor macros.

title: Example
description: Example configuration file.
output: docs
files:
  - header.hpp
  - "*/*.hpp"  # quotes may be needed when using wildcards or other special characters
  - "**/*.hpp"
coverage: coverage.gcov
defines:
  SYMBOL: value
  DEFINED_BUT_EMPTY_SYMBOL: ""      
groups:
  - name: top
    title: Top-level group
    description: Description of the top-level group.
    groups:
      - name: next
        title: Next-level group
        description: Description of the next-level group.
  - name: another
    title: Another top-level group.
    description: Demonstration of another top-level group.