Skip to content

Image and diagram gallery

This page is part of the main MkDoxy documentation. The images in the first section pass through Doxygen and MkDoxy during this site's build. The native diagrams in the second section are stored reference outputs generated by Doxygen and Graphviz.

See Images and diagrams for installation, configuration and current support limitations.

Images included by MkDoxy

These seven real image files are referenced by @image html in the ImageExample class. Open the generated API page to see them inside the actual API documentation. JPG and JPEG share one encoding.

Input Rendered image Origin
SVG SVG pipeline diagram Authored vector source
PNG PNG build stages Drawing commands in the raster generator
JPG JPEG illustrative signal Raster generator; lossy encoding
JPEG JPEG illustrative bars Raster generator; alternative JPEG extension
GIF Animated GIF build progress Four-frame animation from the raster generator
BMP BMP pixel grid Raster generator; uncompressed encoding
WebP WebP illustrative heatmap Raster generator; lossless encoding

These are illustrative drawings, not measurements of project performance. Only regenerating raster inputs requires Pillow; ordinary documentation builds consume the stored files. No Graphviz installation is required for this section.

Actual Doxygen image comments
/**
 * Build documentation from source code.
 *
 * The following assets are owned test fixtures. Doxygen copies these files;
 * it does not generate their pixel content. Raster sources are generated by
 * generate_assets.py; pipeline.svg is authored directly.
 *
 * SVG: resolution-independent pipeline diagram.
 * @image html pipeline.svg "Documentation build pipeline"
 *
 * PNG: lossless build-stage illustration.
 * @image html stages.png "Build stages"
 *
 * JPG: a lossy illustrative signal plot.
 * @image html signal.jpg "Illustrative signal"
 *
 * JPEG: the alternative extension for the same image format.
 * @image html bars.jpeg "Illustrative bars"
 *
 * GIF: an animated four-step build.
 * @image html progress.gif "Build progress"
 *
 * BMP: an uncompressed pixel grid.
 * @image html pixels.bmp "Pixel grid"
 *
 * WebP: a lossless illustrative heatmap.
 * @image html coverage.webp "Illustrative heatmap"
 */
class ImageExample {
public:
    /** Generate the API documentation. */
    void build();
};
Raster image generator
"""Regenerate the owned raster fixtures; requires Pillow (not a test dependency).

Run this script explicitly when changing fixtures. Normal tests consume the
versioned images and require no Pillow installation. The SVG is authored directly.
"""

import math
from pathlib import Path

from PIL import Image, ImageDraw, ImageFont

OUTPUT = Path(__file__).parent / "images"
SIZE = (640, 260)
COLORS = ("#4051b5", "#009688", "#ff9800", "#9c27b0")


def canvas(title: str) -> tuple[Image.Image, ImageDraw.ImageDraw]:
    image = Image.new("RGB", SIZE, "#f0f4f8")
    draw = ImageDraw.Draw(image)
    font = ImageFont.load_default(size=22)
    draw.text((24, 16), title, fill="#172b4d", font=font)
    return image, draw


def generate() -> None:
    OUTPUT.mkdir(exist_ok=True)
    image, draw = canvas("PNG: build stages")
    for index, label in enumerate(("Source", "XML", "Markdown", "HTML")):
        left = 24 + index * 152
        draw.rounded_rectangle((left, 80, left + 138, 168), radius=12, fill=COLORS[index])
        draw.text((left + 12, 112), label, fill="white", font=ImageFont.load_default(size=18))
    image.save(OUTPUT / "stages.png", optimize=False)

    image, draw = canvas("JPEG: illustrative signal")
    points = [(x, 150 - int(55 * math.sin(x / 43))) for x in range(24, 616)]
    draw.line(points, fill=COLORS[0], width=5)
    image.save(OUTPUT / "signal.jpg", quality=90)

    image, draw = canvas("JPEG extension: illustrative bars")
    for index in range(8):
        x = 26 + index * 74
        height = 30 + (index * 31) % 130
        draw.rectangle((x, 220 - height, x + 48, 220), fill=COLORS[index % 4])
    image.save(OUTPUT / "bars.jpeg", quality=90)

    frames = []
    for active in range(4):
        image, draw = canvas("GIF: animated build progress")
        for index in range(4):
            x = 24 + index * 152
            draw.rounded_rectangle(
                (x, 90, x + 138, 170), radius=12, fill=COLORS[index] if index <= active else "#cfd8e3"
            )
            draw.text((x + 52, 114), str(index + 1), fill="white", font=ImageFont.load_default(size=24))
        frames.append(image)
    frames[0].save(OUTPUT / "progress.gif", save_all=True, append_images=frames[1:], duration=650, loop=0)

    image, draw = canvas("BMP: pixel grid")
    for y in range(7):
        for x in range(20):
            color = COLORS[(x // 3 + y // 2) % 4]
            draw.rectangle((24 + x * 29, 68 + y * 23, 50 + x * 29, 88 + y * 23), fill=color)
    image.save(OUTPUT / "pixels.bmp")

    image, draw = canvas("WebP: illustrative heatmap")
    for y in range(6):
        for x in range(18):
            value = (x * 13 + y * 29) % 200
            color = (40 + value // 4, 100 + value // 2, 220 - value // 3)
            draw.rounded_rectangle((24 + x * 33, 68 + y * 27, 54 + x * 33, 92 + y * 27), radius=3, fill=color)
    image.save(OUTPUT / "coverage.webp", lossless=True)


if __name__ == "__main__":
    generate()

Diagrams generated by native Doxygen

The following are native Doxygen outputs embedded as static illustrations. Automatic rendering of these graph elements by MkDoxy is not implemented. The SVG and PNG variants were generated from the same C++ or text input. Normal site builds use the stored illustrations and do not run Graphviz.

Diagram SVG example Raster variant
Inheritance Native inheritance graph PNG
Collaboration Native collaboration graph PNG
Includes Native include graph PNG
Included by Native inverse include graph PNG
Calls Native call graph PNG
Callers Native caller graph PNG
Inline dot Native inline dot graph PNG
External dotfile Native dotfile graph PNG
Inline msc Native inline sequence chart PNG
External mscfile Native external sequence chart PNG
C++ declarations: inheritance and collaboration
#pragma once

namespace gallery {

/** Supplies a value to the documentation builder. */
class Input {
public:
    /** Read the next input value. */
    int read();
};

/** Converts a value to a rendered representation. */
class Renderer {
public:
    /** Render the supplied value. */
    int draw(int value);
};

/** Common interface for documentation builders. */
class BaseBuilder {
public:
    /** Build documentation. */
    virtual void build() = 0;
};

/**
 * Uses Input and Renderer to build documentation.
 * Doxygen derives inheritance, collaboration and call graphs from this code.
 */
class DocumentBuilder : public BaseBuilder {
    Input input_;
    Renderer renderer_;

public:
    /** Read the input, then render its value.
     * @callgraph
     * @callergraph
     */
    void build() override;
};

/** Read a value for the standalone build entry point. */
int read_value();

/** Render a value for the standalone build entry point. */
int render_value(int value);

/** Entry point used to demonstrate caller graphs. */
void run_build(DocumentBuilder &builder);

} // namespace gallery
C++ implementations: calls and callers
#include "model.h"

namespace gallery {

int Input::read() { return 42; }

int Renderer::draw(int value) { return value * 2; }

void DocumentBuilder::build() {
    int value = input_.read();
    renderer_.draw(value);
}

int read_value() { return 42; }

int render_value(int value) { return value * 2; }

void run_build(DocumentBuilder &builder) {
    int value = read_value();
    render_value(value);
    builder.build();
}

} // namespace gallery
Inline Doxygen graph commands
#include "model.h"

/**
 * @mainpage Native Doxygen diagram gallery
 *
 * These diagrams are generated by Doxygen, not copied from pre-existing image files.
 * Native Doxygen graph rendering is separate from MkDoxy's image-copy feature.
 *
 * @section inline_dot Inline Graphviz definition
 * @dot
 * digraph Build {
 *   rankdir=LR;
 *   node [shape=box, style=filled, fillcolor="#eef2ff", fontname="sans-serif"];
 *   Source -> XML -> Markdown -> HTML;
 * }
 * @enddot
 *
 * @section dot_file External Graphviz file
 * @dotfile states.dot "Build states"
 *
 * @section sequence Inline sequence chart
 * @msc
 * client,worker,cache;
 * client=>worker [label="build()"];
 * worker=>cache [label="lookup(source hash)"];
 * cache>>worker [label="miss"];
 * worker>>client [label="HTML + assets"];
 * @endmsc
 *
 * @section sequence_file External sequence chart
 * @mscfile exchange.msc "Review sequence"
 */
External Graphviz definition
digraph States {
    rankdir=LR;
    node [shape=box, style="rounded,filled", fillcolor="#e0f2f1", fontname="sans-serif"];
    Source -> XML [label="Doxygen"];
    XML -> Markdown [label="MkDoxy"];
    Markdown -> HTML [label="MkDocs"];
    XML -> Error [label="invalid input", color="#c62828"];
    Error [fillcolor="#ffebee"];
}
External sequence chart definition
msc {
    contributor,ci,maintainer;
    contributor=>ci [label="push contribution"];
    ci>>contributor [label="tests pass"];
    contributor=>maintainer [label="request review"];
    maintainer>>contributor [label="approve / feedback"];
}
Native Doxygen configuration
PROJECT_NAME = "Native Doxygen diagrams"
OUTPUT_DIRECTORY = output
INPUT = .
FILE_PATTERNS = *.h *.cpp
EXTRACT_ALL = YES
EXTRACT_PRIVATE = YES
GENERATE_HTML = YES
GENERATE_XML = YES
GENERATE_LATEX = NO
HAVE_DOT = YES
DOT_IMAGE_FORMAT = svg
DOT_CLEANUP = NO
DOT_NUM_THREADS = 1
CLASS_GRAPH = YES
COLLABORATION_GRAPH = YES
CALL_GRAPH = YES
CALLER_GRAPH = YES
INCLUDE_GRAPH = YES
INCLUDED_BY_GRAPH = YES
SOURCE_BROWSER = YES
INLINE_SOURCES = YES
REFERENCES_RELATION = YES
REFERENCED_BY_RELATION = YES
DOTFILE_DIRS = .
MSCFILE_DIRS = .
QUIET = YES
WARN_IF_UNDOCUMENTED = NO

Reproduce the examples

The setup and regeneration instructions explain how to build the standalone gallery and refresh the static diagrams. Regenerating them requires Graphviz; their output can vary with tool and font versions. PlantUML and Dia examples are not generated here.