Skip to content

Commit 9461868

Browse files
ramzanbhuttoramzanbhutto
committed
Added Doxygen Blog
1 parent 306dbe7 commit 9461868

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

50 files changed

+8746
-23
lines changed

‎content/posts/Doxygen.md‎

Lines changed: 269 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,269 @@
1+
---
2+
title: "Doxygen + PlantUML + Graphviz: Build Automated, Beautiful Project Documentation"
3+
date: 2025-09-02
4+
tags: ["C++", "Documentation", "Doxygen", "PlantUML", "Graphviz", "Open Source"]
5+
author: "Ramzan Bhutto"
6+
description: "Learn how to use Doxygen to generate stunning project documentation, complete with diagrams, graphs, and professional structure."
7+
---
8+
9+
## 🔹 What is Doxygen?
10+
11+
[Doxygen](https://www.doxygen.nl/) is a documentation generator tool that:
12+
- Parses your code (C++, Python, Java, JavaScript, and many other languages).
13+
- Extracts specially formatted comments.
14+
- Automatically generates documentation in multiple formats:
15+
- **HTML** (viewable in any browser)
16+
- **PDF / LaTeX**
17+
- **Man pages**
18+
- **Graphs and diagrams** (with Graphviz)
19+
20+
It’s like having a personal technical writer who works directly from your source code.
21+
22+
---
23+
24+
## 🔹 What is a Doxyfile?
25+
26+
The `Doxyfile` is the **configuration file** Doxygen uses to determine:
27+
- Which files to document
28+
- Which languages to parse
29+
- Whether to generate graphs or UML diagrams
30+
- What output format to use (HTML, PDF, etc.)
31+
32+
You can generate a default `Doxyfile` with:
33+
34+
```bash
35+
doxygen -g
36+
```
37+
This creates a `Doxyfile` in your current directory, which you can then edit to customize your documentation.
38+
39+
---
40+
41+
## 🔹 Why Use PlantUML and Graphviz with Doxygen?
42+
While Doxygen can generate basic diagrams, integrating **PlantUML** and **Graphviz** allows you to create **more complex and visually appealing diagrams**.
43+
- **PlantUML** lets you create UML diagrams using a simple text-based syntax.
44+
- **Graphviz** generates graphs and diagrams from DOT files, which Doxygen can produce.
45+
This combination enhances your documentation with:
46+
- Class diagrams
47+
- Sequence diagrams
48+
- State diagrams
49+
- Call graphs
50+
- Collaboration diagrams
51+
52+
---
53+
## 🔹 Installing Doxygen, PlantUML and Graphviz
54+
### Step 1: Install doxygen
55+
- Ubuntu
56+
```bash
57+
sudo apt-get install doxygen
58+
```
59+
- Arch Linux
60+
```bash
61+
sudo pacman -S doxygen
62+
```
63+
64+
### Step 2: Install Graphviz
65+
- Ubuntu
66+
```bash
67+
sudo apt-get install graphviz
68+
```
69+
- Arch Linux
70+
```bash
71+
sudo pacman -S graphviz
72+
```
73+
74+
### Step 3: Install PlantUML
75+
PlantUML requires Java to run. Make sure you have Java installed, then install PlantUML:
76+
- Ubuntu
77+
```bash
78+
sudo apt-get install plantuml
79+
```
80+
- Arch Linux
81+
```bash
82+
sudo pacman -S plantuml
83+
```
84+
85+
---
86+
87+
## 🔹 Why Write and Configure Your Own Doxyfile?
88+
89+
When you run:
90+
91+
```bash
92+
doxygen -g
93+
```
94+
After running this, Doxygen generates a default Doxyfile with nearly 3000 lines of configuration.While it contains every possible option, it can be overwhelming and cluttered, especially for beginners. It includes many settings that you may never use, making it hard to find the options you actually need.
95+
By writing your own Doxyfile from scratch, you can:
96+
- **Keep it clean and simple**: Only include the settings you actually need.
97+
- **Understand each option**: Learn what each configuration does, making it easier to customize later.
98+
- **Tailor it to your project**: Focus on the specific features and outputs that matter to you.
99+
100+
---
101+
102+
## 🔹 Understanding Doxyfile configuration
103+
Now, let’s go through each important section of a Doxyfile step-by-step.
104+
First, create a new file named `Doxyfile` in your project directory and open it in your favorite text editor.
105+
106+
### 1. Project Information
107+
The first section defines basic metadata about your project.
108+
```bash
109+
PROJECT_NAME = "MyProject"
110+
PROJECT_BRIEF = "A brief description of MyProject"
111+
PROJECT_LOGO = "path/to/logo.png"
112+
OUTPUT_DIRECTORY = docs
113+
```
114+
- `PROJECT_NAME`: The name of your project.
115+
- `PROJECT_BRIEF`: A short description of your project.
116+
- `PROJECT_LOGO`: Path to a logo image to include in the documentation.
117+
- `OUTPUT_DIRECTORY`: Where the generated documentation will be saved.
118+
119+
### 2. Input Sources
120+
This section specifies which files and directories to include in the documentation.
121+
```bash
122+
INPUT = .
123+
FILE_PATTERNS = *.cpp *.h *.py
124+
RECURSIVE = YES
125+
```
126+
- `INPUT`: The directories or files to scan for documentation.
127+
- `FILE_PATTERNS`: File extensions as per language used in the project.
128+
- `RECURSIVE`: If set to `YES`, Doxygen will search subdirectories. If `NO`, it will only scan the root directory.
129+
130+
### 3. Build Options
131+
This section controls how Doxygen processes the input files.
132+
```bash
133+
EXTRACT_ALL = YES
134+
EXTRACT_PRIVATE = YES
135+
EXTRACT_STATIC = YES
136+
EXTRACT_LOCAL_CLASSES = YES
137+
EXTRACT_LOCAL_METHODS = YES
138+
```
139+
- `EXTRACT_ALL`: If `YES`, Doxygen will document all entities, even those without comments.
140+
- `EXTRACT_PRIVATE`: If `YES`, private class members will be included in the documentation.
141+
- `EXTRACT_STATIC`: If `YES`, static members will be documented.
142+
- `EXTRACT_LOCAL_CLASSES`: If `YES`, local classes (defined within functions) will be documented.
143+
- `EXTRACT_LOCAL_METHODS`: If `YES`, local methods (defined within functions) will be documented.
144+
145+
### 4. Output Formats
146+
This section specifies which output formats to generate.
147+
```bash
148+
GENERATE_HTML = YES
149+
GENERATE_LATEX = NO
150+
```
151+
- `GENERATE_HTML`: If `YES`, Doxygen will generate HTML documentation.
152+
- `GENERATE_LATEX`: If `YES`, Doxygen will generate LaTeX documentation (useful for creating PDFs).
153+
154+
### 5. Graphs and Diagrams
155+
This section enables the generation of graphs and diagrams using Graphviz and PlantUML.
156+
```bash
157+
HAVE_DOT = YES
158+
DOT_PATH =
159+
DOT_IMAGE_FORMAT = svg
160+
CALL_GRAPH = YES
161+
CALLER_GRAPH = YES
162+
CLASS_DIAGRAMS = YES
163+
UML_LOOK = YES
164+
DOT_GRAPH_MAX_NODES = 50
165+
INTERACTIVE_SVG = YES
166+
```
167+
- `HAVE_DOT`: If `YES`, enables Graphviz support for generating graphs.
168+
- `DOT_PATH`: Path to the Graphviz `dot` executable (if not in your system PATH).
169+
- `DOT_IMAGE_FORMAT`: The format for generated graph images (e.g., `svg`, `png`).
170+
- `CALL_GRAPH`: If `YES`, generates call graphs for functions.
171+
- `CALLER_GRAPH`: If `YES`, generates caller graphs for functions.
172+
- `CLASS_DIAGRAMS`: If `YES`, generates class diagrams.
173+
- `UML_LOOK`: If `YES`, uses a UML-like style for class diagrams.
174+
- `DOT_GRAPH_MAX_NODES`: Limits the number of nodes in generated graphs to avoid clutter.
175+
- `INTERACTIVE_SVG`: If `YES`, generates interactive SVG diagrams(zoomable and pannable).
176+
177+
> Tip : If your graphs are too cluttered, try reducing `DOT_GRAPH_MAX_NODES` or simplifying your code structure.
178+
179+
### 6. PlantUML Integration
180+
To integrate PlantUML, you need to specify the path to the PlantUML jar file.
181+
```bash
182+
PLANTUML_JAR_PATH = /path/to/plantuml.jar
183+
```
184+
- `PLANTUML_JAR_PATH`: Path to the PlantUML jar file. This allows Doxygen to generate UML diagrams using PlantUML.
185+
186+
### 7. Complete Doxyfile Example
187+
Here’s a complete example of a simple Doxyfile with the above configurations:
188+
```bash
189+
# --- Project Information ---
190+
PROJECT_NAME = "MyProject"
191+
PROJECT_BRIEF = "A brief description of MyProject"
192+
PROJECT_LOGO = "path/to/logo.png"
193+
OUTPUT_DIRECTORY = docs
194+
195+
# --- Input Sources ---
196+
INPUT = .
197+
FILE_PATTERNS = *.cpp *.h *.hpp *.py *.java *.js *.ts *.go *.cs
198+
RECURSIVE = YES
199+
200+
# --- Build Options ---
201+
EXTRACT_ALL = YES
202+
EXTRACT_PRIVATE = YES
203+
EXTRACT_STATIC = YES
204+
EXTRACT_LOCAL_CLASSES = YES
205+
EXTRACT_LOCAL_METHODS = YES
206+
207+
# --- Documentation Output ---
208+
GENERATE_HTML = YES
209+
GENERATE_LATEX = NO
210+
211+
# --- Diagrams & Graphs ---
212+
HAVE_DOT = YES
213+
DOT_PATH =
214+
DOT_IMAGE_FORMAT = svg
215+
CALL_GRAPH = YES
216+
CALLER_GRAPH = YES
217+
CLASS_DIAGRAMS = YES
218+
UML_LOOK = YES
219+
DOT_GRAPH_MAX_NODES = 50
220+
INTERACTIVE_SVG = YES
221+
222+
223+
# --- PlantUML Integration ---
224+
PLANTUML_JAR_PATH = /path/to/plantuml.jar
225+
226+
```
227+
228+
### 7. Running Doxygen
229+
Once your Doxyfile is configured, you can generate the documentation by running in your terminal:
230+
```bash
231+
doxygen Doxyfile
232+
```
233+
Then, open the generated HTML documentation in your web browser:
234+
```bash
235+
xdg-open docs/html/index.html # Linux
236+
```
237+
```bash
238+
open docs/html/index.html # macOS
239+
```
240+
```bash
241+
start docs\html\index.html # Windows
242+
```
243+
> It will open the main page of your generated documentation, there you can navigate through classes, files, and diagrams. Following is the sample output of the documentation:
244+
![Doxygen Sample Output](/doxygen-document.png)
245+
246+
---
247+
248+
## 🔹 How it works
249+
Below is a visual representation of how Doxygen, Graphviz, and PlantUML work together:
250+
251+
![Doxygen Flowchart](/doxygen-working.png)
252+
253+
---
254+
255+
## 🔹 Conclusion
256+
Using Doxygen with PlantUML and Graphviz allows you to create **comprehensive, visually appealing documentation** for your projects with minimal effort. By writing a clean and tailored Doxyfile, you can ensure that your documentation meets your specific needs and showcases your code effectively. It can save you time, improve code maintainability, and enhance collaboration within your team.
257+
>**In short:** Well-documented projects are easier to **maintain**, **scale**, and **share**.
258+
> If you want your code to speak for itself, **Doxygen is one of the best investments you can make**.
259+
260+
---
261+
262+
## 🔹 Additional Resources
263+
- [Doxygen Official Documentation](https://www.doxygen.nl/manual/index.html)
264+
- [PlantUML Official Website](https://plantuml.com/)
265+
- [Graphviz Official Website](https://graphviz.org/)
266+
267+
---
268+
269+
Happy Documenting! 🚀

‎latex/Makefile‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
LATEX_CMD?=pdflatex
2+
MKIDX_CMD?=makeindex
3+
BIBTEX_CMD?=bibtex
4+
LATEX_COUNT?=8
5+
MANUAL_FILE?=refman
6+
7+
all: $(MANUAL_FILE).pdf
8+
9+
pdf: $(MANUAL_FILE).pdf
10+
11+
$(MANUAL_FILE).pdf: clean $(MANUAL_FILE).tex
12+
$(LATEX_CMD) $(MANUAL_FILE) || \
13+
if [ $$? != 0 ] ; then \
14+
\echo "Please consult $(MANUAL_FILE).log to see the error messages" ; \
15+
false; \
16+
fi
17+
$(MKIDX_CMD) $(MANUAL_FILE).idx
18+
$(LATEX_CMD) $(MANUAL_FILE) || \
19+
if [ $$? != 0 ] ; then \
20+
\echo "Please consult $(MANUAL_FILE).log to see the error messages" ; \
21+
false; \
22+
fi
23+
latex_count=$(LATEX_COUNT) ; \
24+
while grep -E -s 'Rerun (LaTeX|to get cross-references right|to get bibliographical references right)' $(MANUAL_FILE).log && [ $$latex_count -gt 0 ] ;\
25+
do \
26+
echo "Rerunning latex...." ;\
27+
$(LATEX_CMD) $(MANUAL_FILE) || \
28+
if [ $$? != 0 ] ; then \
29+
\echo "Please consult $(MANUAL_FILE).log to see the error messages" ; \
30+
false; \
31+
fi; \
32+
latex_count=`expr $$latex_count - 1` ;\
33+
done
34+
$(MKIDX_CMD) $(MANUAL_FILE).idx
35+
$(LATEX_CMD) $(MANUAL_FILE) || \
36+
if [ $$? != 0 ] ; then \
37+
\echo "Please consult $(MANUAL_FILE).log to see the error messages" ; \
38+
false; \
39+
fi
40+
41+
clean:
42+
rm -f *.ps *.dvi *.aux *.toc *.idx *.ind *.ilg *.log *.out *.brf *.blg *.bbl $(MANUAL_FILE).pdf

0 commit comments

Comments
 (0)