1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
|
Code Blocks
===========
Breathe supports rendering code blocks with syntax highlighting provided by the
`Pygments <https://pygments.org/>`_ library. By default, Breathe will assume
that code blocks match the language of the source file, but you can also specify
the language of the code blocks using
`Doxygen's code command <https://www.doxygen.nl/manual/commands.html#cmdcode>`_
or `MarkDown's fenced code blocks <https://www.doxygen.nl/manual/markdown.html#md_fenced>`_.
.. note::
Any hyperlinked text found within the code blocks rendered with Doxygen's HTML output
will not be hyperlinked in any Sphinx output due to the use of the Pygments library.
As a benefit, a code-block's syntax highlighting can be any syntax supported by
Pygments (which is much more than only the languages supported by Doxygen's parsers).
The Doxygen syntax for code blocks supports specifying the language as follows:
.. code-block::
\code{.py}
class Python:
pass
\endcode
@code{.cpp}
class Cpp {};
@endcode
This technique can also be utilized from MarkDown syntax/files
.. code-block:: markdown
```py
class Python:
pass
```
```cpp
class Cpp {};
```
Breathe will pass the language specified to Pygments to get accurate
highlighting. If no language is explicitly provided (either from ``\code``
command or via Doxygen's XML output about the language documented), then
Pygments will try to guess what syntax the code block is using (based on
the code block's contents).
Examples
--------
The following should render with standard C/C++ highlighting. Notice, the
syntax is automatically highlighted as C++ because the documented function
exists in a C++ source file.
----
.. code-block:: cpp
/** A function with an unannotated code block with C/C++ code.
*
* @code
* char *buffer = new char[42];
* int charsAdded = sprintf(buffer, "Tabs are normally %d spaces\n", 8);
* @endcode
*/
void with_standard_code_block();
----
.. doxygenfunction:: with_standard_code_block
:path: ../../examples/specific/code_blocks/xml
:no-link:
----
The following should render with no detected highlighting.
Notice, there is no syntax highlighting because Pygments does not
recognize the code block's contained syntax as a C++ snippet.
----
.. code-block:: cpp
/** A function with an unannotated code block with non-C/C++ code.
*
* @code
* set(user_list A B C)
* foreach(element ${user_list})
* message(STATUS "Element is ${element}")
* endforeach()
* @endcode
*
* Another code-block that explicitly remains not highlighted.
* @code{.unparsed}
* Show this as is.
* @endcode
*/
void with_unannotated_cmake_code_block();
----
.. doxygenfunction:: with_unannotated_cmake_code_block
:path: ../../examples/specific/code_blocks/xml
:no-link:
----
The following should render with specified CMake highlighting. Here, the syntax
highlighting is explicitly recognized as a CMake script snippet which overrides
the inherent C++ context.
----
.. code-block:: cpp
/** A function with an annotated cmake code block.
*
* @code{.cmake}
* set(user_list A B C)
* foreach(element ${user_list})
* message(STATUS "Element is ${element}")
* endforeach()
* @endcode
*/
void with_annotated_cmake_code_block();
----
.. doxygenfunction:: with_annotated_cmake_code_block
:path: ../../examples/specific/code_blocks/xml
:no-link:
.. warning::
Pygments will raise a warning in the Sphinx build logs if
the specified syntax does conform the specified syntax's convention(s).
|
