Usage¶

MkDoxy creates API documentation based on Doxygen comments and code snippets in your markdown files.

site_name: "My documentation"

theme:
  name: material

plugins:
  - search
  - mkdoxy:
      projects:
        myProjectCpp: # name of project must be alphanumeric + numbers (without spaces)
          src-dirs: path/to/src/project1 # path to source code (support multiple paths separated by space) => INPUT
          full-doc: True # if you want to generate full documentation
          doxy-cfg: # standard doxygen configuration (key: value)
            FILE_PATTERNS: "*.cpp *.h*" # specify file patterns to filter out
            RECURSIVE: True # recursive search in source directories

How does it work¶

MkDoxy runs Doxygen to generate XML files from your source code (this is executed only if the source code has changed).
MkDoxy parses the XML files and creates a recursive structure of each project.
Plugin generates markdown files from the recursive structure based on Jinja templates.
Find snippets tags in the markdown files and replace them with the configured code snippets.
Plugin includes the generated markdown files in the final documentation.
MkDocs generates the final documentation.

Multiple projects¶

MkDoxy supports multiple projects in one repository. Each project must have its own configuration. The configuration is specified in the projects section of the MkDoxy configuration. The name of the project must be alphanumeric + numbers (without spaces). The name of the project is used to identify the project in the snippet tags.

Configure multiple projects

plugins:
  - mkdoxy:
      projects:
        apiProject1: # name of project must be alphanumeric + numbers (without spaces)
          src-dirs: path/to/src/project1
          ...
        apiProject2:
          src-dirs: path/to/src/project2
          ...
        predefinedProject3:
            src-dirs: path/to/src/project3
            ...

Custom Jinja templates¶

Custom templates can be used to change the appearance of the generated documentation. Each custom template file will replace the default template file. Custom templates have to end with .jinja2, .j2, or .jinja extension. So you do not have to create a custom template for the whole documentation, but only for the parts you want to change.

Custom Jinja templates

plugins:
  - mkdoxy:
      projects:
        projectWithCustomTemplate:
            src-dirs: path/to/src/project1
            template-dir: path/to/userDefined/templates # optional (default is mkdoxy/templates) - custom template will replace default template

Custom Doxygen configuration¶

MkDoxy supports custom Doxygen configuration for each project. The configuration is specified in the doxy-cfg section of the project configuration. The configuration is passed to Doxygen as a string. The configuration is merged with the default configuration.

Default Doxygen configuration

"INPUT": self.doxygenSource, # path to source code
"OUTPUT_DIRECTORY": self.tempDoxyFolder, # path to temporary folder
"DOXYFILE_ENCODING": "UTF-8", # encoding of doxygen configuration file
"GENERATE_XML": "YES", # generate XML files (required by mkdoxy)
"RECURSIVE": "YES", # recursive search for source files
"SHOW_NAMESPACES": "YES", # show namespaces in documentation
"GENERATE_HTML": "NO", # do not generate HTML files (mkdoxy generates documentation from XML files)
"GENERATE_LATEX": "NO", # do not generate LaTeX files

Doxygen configuration options: www.doxygen.nl/manual/config.html

Custom Doxygen configuration - override default configuration

plugins:
  - mkdoxy:
      projects:
        pythonProject:
          src-dirs: path/to/src/pythonProject
          full-doc: True
          doxy-cfg:
            FILE_PATTERNS: "*.py"
            EXAMPLE_PATH: ""
            RECURSIVE: True
            OPTIMIZE_OUTPUT_JAVA: True
            JAVADOC_AUTOBRIEF: True
            EXTRACT_ALL: True
            ...

Configure custom Doxygen configuration file¶

If you want to use a standard Doxygen configuration file, you can specify the path to the file using the doxygen-config option in the plugin configuration.

Add custom Doxygen configuration file

plugins:
  - mkdoxy:
      projects:
        myProjectCpp:
          src-dirs: ...
          doxy-cfg-file: path/to/Doxyfile  # relative path to the Doxygen configuration file (relative to the mkdocs.yml file)
          doxy-cfg:       # standard doxygen configuration (key: value)
            FILE_PATTERNS: ... # other configuration options - merge (this will override the configuration from the Doxyfile)

How is it implemented?

doxyrun.py

        """! Set the Doxygen configuration.
        @details If a custom Doxygen config file is provided, it will be used. Otherwise, default options will be used.
        @details Order of application of parameters:
        @details 1. Custom Doxygen config file
        @details 2. If not provided, default options - in documentation
        @details 3. New Doxygen config options from mkdocs.yml
        @details 3. Overwrite INPUT and OUTPUT_DIRECTORY with the provided values for correct plugin operation.

        @details Overwrite options description:
        @details - INPUT: <doxygenSource>
        @details - OUTPUT_DIRECTORY: <tempDoxyFolder>

        @details Default Doxygen config options:
        @details - DOXYFILE_ENCODING: UTF-8
        @details - GENERATE_XML: YES
        @details - RECURSIVE: YES
        @details - EXAMPLE_PATH: examples
        @details - SHOW_NAMESPACES: YES
        @details - GENERATE_HTML: NO
        @details - GENERATE_LATEX: NO
        @param doxyCfgNew: (dict) New Doxygen config options that will be
         added to the default config (new options will overwrite default options)
        @return: (dict) Doxygen configuration.
        """
        doxyCfg = {}

        if self.doxyConfigFile is not None and self.doxyConfigFile != "":
            try:
                with open(self.doxyConfigFile, "r") as file:
                    doxyCfg.update(self.str2dox_dictstr2dox_dict(file.read()))
            except FileNotFoundError as e:
                raise DoxygenCustomConfigNotFound(
                    f"Custom Doxygen config file not found: {self.doxyConfigFile}\n"
                    f"Make sure the path is correct."
                    f"Look at https://mkdoxy.kubaandrysek.cz/usage/advanced/#configure-custom-doxygen-configuration-file."
                ) from e
        else:
            doxyCfg = {
                "DOXYFILE_ENCODING": "UTF-8",
                "GENERATE_XML": "YES",
                "RECURSIVE": "YES",
                "EXAMPLE_PATH": "examples",
                "SHOW_NAMESPACES": "YES",
                "GENERATE_HTML": "NO",
                "GENERATE_LATEX": "NO",
            }

        doxyCfg.update(doxyCfgNew)
        doxyCfg["INPUT"] = self.doxygenSource
        doxyCfg["OUTPUT_DIRECTORY"] = self.tempDoxyFolder
        return doxyCfg

Advanced configuration¶

mkdocs.yml configuration

plugins:
  - mkdoxy:
      projects:
        apiProject1: # name of project must be alphanumeric + numbers (without spaces)
          src-dirs: path/to/src/project1
          full-doc: True
          doxy-cfg:
            FILE_PATTERNS: "*.cpp *.h*"
            EXAMPLE_PATH: examples
            RECURSIVE: True
        apiProject2:
          src-dirs: path/to/src/project2
          full-doc: True
          template-dir: path/to/userDefined/templates # optional (default is mkdoxy/templates) - custom template will replace default template
          # Example of custom template: https://mkdoxy-demo.kubaandrysek.cz/esp/annotated/
          doxy-cfg:
            FILE_PATTERNS: "*.py"
            EXAMPLE_PATH: ""
            RECURSIVE: True
            OPTIMIZE_OUTPUT_JAVA: True
            JAVADOC_AUTOBRIEF: True
            EXTRACT_ALL: True
        predefinedProject3:
          src-dirs: path/to/src/project3
          full-doc: False
          doxy-cfg:
            PREDEFINED: __cplusplus # example there: https://github.com/kuba2k2/libretuya/blob/master/mkdocs.yml
            CASE_SENSE_NAMES: NO
...
nav:
  - Home: 'index.md'
  - API:
      - Project 1:
          - 'Links': 'apiProject1/links.md'
          - 'Classes':
              - 'Class List': 'apiProject1/annotated.md'
              - 'Class Index': 'apiProject1/classes.md'
              - 'Class Hierarchy': 'apiProject1/hierarchy.md'
              - 'Class Members': 'apiProject1/class_members.md'
              - 'Class Member Functions': 'apiProject1/class_member_functions.md'
              - 'Class Member Variables': 'apiProject1/class_member_variables.md'
              - 'Class Member Typedefs': 'apiProject1/class_member_typedefs.md'
              - 'Class Member Enumerations': 'apiProject1/class_member_enums.md'
          - 'Namespaces':
              - 'Namespace List': 'apiProject1/namespaces.md'
              - 'Namespace Members': 'apiProject1/namespace_members.md'
              - 'Namespace Member Functions': 'apiProject1/namespace_member_functions.md'
              - 'Namespace Member Variables': 'apiProject1/namespace_member_variables.md'
              - 'Namespace Member Typedefs': 'apiProject1/namespace_member_typedefs.md'
              - 'Namespace Member Enumerations': 'apiProject1/namespace_member_enums.md'
          - 'Functions': 'apiProject1/functions.md'
          - 'Variables': 'apiProject1/variables.md'
          - 'Macros': 'apiProject1/macros.md'
          - 'Files': 'apiProject1/files.md'
      - Project 2:
...

use_directory_urls: true # (optional) for better links without .html extension