Install & use Doxygen via Docker

Doxygen & its use cases

Doxygen is a documentation generator tool that can be used to generate documentation for software projects in various programming languages, such as C++, Java, Python, and more. It extracts comments from source code and generates documentation in various formats, such as HTML, PDF, and LaTeX.

Doxygen has several use cases, including:

• Code documentation: Doxygen can extract comments in the source code and create documentation that describes the various functions, classes, and other elements of the code. This documentation can be very useful for developers who need to understand the code, and for new developers who are trying to learn how to work with the code.

• API documentation: Doxygen can be used to generate documentation for APIs (Application Programming Interfaces), which are used to interact with software libraries or frameworks. This documentation can be very helpful for developers who are using the API, as it can provide information on how to use the API and what its various functions and parameters do.

• Project documentation: Doxygen can generate documentation for entire software projects, including not just the code, but also the project structure, requirements, and other information. This can be useful for project managers, stakeholders, and other non-technical team members who need to understand the project.

• Code analysis: Doxygen can also be used to analyze code and identify potential issues, such as unused variables, missing function declarations, and more. This can be helpful for developers who are trying to improve the quality of their code or identify potential bugs before they cause problems.

Install Docker or Docker Rootless

How to install Docker rootlessHow to install Docker rootless

Install docker on Ubuntu/DebianInstall docker on Ubuntu/Debian

Running Doxygen with Docker!

the premise : you have your source code in a folder named: source your output is going to be in a folder named: output your doxygen file is named: Doxygen

your doxygen file has at least these two entries modified: INPUT = /source OUTPUT_DIRECTORY = /output

you can also enable dot HAVE_DOT               = YES

and IF you want call graphs enabled : CALL_GRAPH             = YES

docker run --rm -it -v ./source:/source -v ./output:/output -v ./Doxygen:/Doxygen ghcr.io/kingpin/doxygen-docker:latest

This command runs a Docker container with the image “ghcr.io/kingpin/doxygen-docker:latest”, which is a pre-configured Doxygen environment. The “run” command specifies that the container should be run, and the “–rm” flag specifies that the container should be removed after it exits.

The “-it” flag allocates a pseudo-TTY and enables interactive mode, which allows the user to interact with the container’s shell. The “-v” flag mounts the local directories “./source”, “./output”, and file called “./Doxygen” to the container’s directories “/source”, “/output”, and file “/Doxygen”, respectively. This enables the container to access files and folders from the local machine.

Overall, this command sets up a Doxygen environment in a Docker container and mounts local directories to the container so that Doxygen can generate documentation from files in the mounted source directory and output the results to the mounted output directory.

This will output everything to the /output folder. for example if you enabled html output, there will be ./output/html which you can then use a webserver to serve. for example :

version: '3'
services:
  doxygen_caddy:
    image: caddy:alpine
    container_name: doxygen_caddy
    restart: unless-stopped
    networks:
      - web
    volumes:
      - /opt/docker/www/trinitycore.net/data/output/html:/var/www/html
      - /opt/docker/www/trinitycore.net/Caddyfile:/etc/caddy/Caddyfile

networks:
  web:

and put this in the caddyfile:

example.com {
  root * /var/www/html
  file_server
}

You can run this manually or add the docker call to a shell script and run it via a cronjob. ** Coming soon same image but with cron built in so it can be run automatically on a schedule.*

Generating a Doxyfile Without Installing Doxygen

Here’s a gotcha that gets people: you need a Doxygen config file before you can run the tool, but you don’t have Doxygen installed locally — that’s the whole point of using Docker. Chicken, meet egg.

The fix is simple: use the same container to generate a default config file first, then tweak it.

# Generate a default Doxyfile in your current directory
docker run --rm -v "$(pwd)":/workspace -w /workspace ghcr.io/kingpin/doxygen-docker:latest doxygen -g Doxygen

This drops a fully commented Doxygen file in your current directory. It’s about 2,500 lines long and documents every option — which sounds terrifying but is actually kind of nice because you can search for any setting by name.

The handful of settings you almost always need to change:

# Tell Doxygen where your source lives (inside the container)
INPUT                  = /source

# Where to write the output (inside the container)
OUTPUT_DIRECTORY       = /output

# Name of your project — shows up in the generated HTML header
PROJECT_NAME           = "My Awesome Project"

# Enable recursive scanning so it finds files in subdirectories
RECURSIVE              = YES

# If you want call graphs (requires Graphviz/dot)
HAVE_DOT               = YES
CALL_GRAPH             = YES
CALLER_GRAPH           = YES

One more thing: if your project has a mix of file types — say C++ headers and some Python utilities — set EXTRACT_ALL = YES. Without it, Doxygen only documents things that have explicit doc comments, and you’ll stare at an empty HTML page wondering what went wrong. EXTRACT_ALL pulls in everything, which is a good starting point before you go back and add proper /** */ comments to the stuff that actually matters.

Related Reading

• Access Docker socket via TCP
• Copying Files Between Docker Containers and Host Machines
• Docker Networking: Connecting to the Host from a Container
• Docker vs Podman: Key Differences
• Executing Commands with Asterisks in Docker