doxygen: support specifying explicit image width/height.

diff --git a/doc/doxygen.rst b/doc/doxygen.rst
index 7129da3a99958c8d343aaa559a5dce4289c22ff4..ccacbb766354ea9293797f1a5318629e0386e33c 100644 (file)
--- a/doc/doxygen.rst
+++ b/doc/doxygen.rst
@@ -555,6 +555,17 @@ single-paragraph item will make sure the enclosing :html:`<p>` is not stripped.
 
 To match the stock HTML output, images that are marked with ``html`` target are
 used. If image name is present, the image is rendered as a figure with caption.
+It's possible affect width/height of the image using the ``sizespec`` parameter
+(unlike stock Doxygen, which makes use of this field only for LaTeX output and
+ignores it for HTML output). The parameter is converted to an inline CSS
+:css:`width` or :css:`height` property, so the value has to contain the units
+as well:
+
+.. code:: c++
+
+    /**
+    @image image.png width=250px
+    */
 
 `Pages, sections and table of contents`_
 ----------------------------------------

diff --git a/doxygen/dox2html5.py b/doxygen/dox2html5.py
index 602f6c2561aaa4a189ad10c28917ec8581c061c7..20211cea9ad6cc4a6e5180f8cdbb9968a214381a 100755 (executable)
--- a/doxygen/dox2html5.py
+++ b/doxygen/dox2html5.py
@@ -1050,14 +1050,20 @@ def parse_desc_internal(state: State, element: ET.Element, immediate_parent: ET.
                 else:
                     logging.warning("{}: image {} was not found in XML_OUTPUT".format(state.current, name))
 
+                sizespec = ''
+                if 'width' in i.attrib:
+                    sizespec = ' style="width: {}"'.format(i.attrib['width'])
+                elif 'height' in i.attrib:
+                    sizespec = ' style="height: {}"'.format(i.attrib['height'])
+
                 caption = i.text
                 if caption:
-                    out.parsed += '<figure class="m-figure{}"><img src="{}" alt="Image" /><figcaption>{}</figcaption></figure>'.format(
+                    out.parsed += '<figure class="m-figure{}"><img src="{}" alt="Image"{} /><figcaption>{}</figcaption></figure>'.format(
                         ' ' + add_css_class if add_css_class else '',
-                        name, html.escape(caption))
+                        name, sizespec, html.escape(caption))
                 else:
-                    out.parsed += '<img class="m-image{}" src="{}" alt="Image" />'.format(
-                        ' ' + add_css_class if add_css_class else '', name)
+                    out.parsed += '<img class="m-image{}" src="{}" alt="Image"{} />'.format(
+                        ' ' + add_css_class if add_css_class else '', name, sizespec)
 
         elif i.tag == 'hruler':
             assert element.tag == 'para' # is inside a paragraph :/

diff --git a/doxygen/test/contents_image/index.html b/doxygen/test/contents_image/index.html
index 738cbbca9b9298b04bf9a407bb91dfcf39705422..93394d5bce513a9b52802dcd7152b5bc220f9b1b 100644 (file)
--- a/doxygen/test/contents_image/index.html
+++ b/doxygen/test/contents_image/index.html
@@ -22,7 +22,7 @@
         <h1>
           My Project
         </h1>
-<p>Image:</p><img class="m-image" src="tiny.png" alt="Image" /><p>Figure:</p><figure class="m-figure"><img src="tiny.png" alt="Image" /><figcaption>Caption</figcaption></figure>
+<p>Image:</p><img class="m-image" src="tiny.png" alt="Image" /><p>Figure:</p><figure class="m-figure"><img src="tiny.png" alt="Image" /><figcaption>Caption</figcaption></figure><p>Explicit width:</p><img class="m-image" src="tiny.png" alt="Image" style="width: 128px" /><p>Explicit height and a caption:</p><figure class="m-figure"><img src="tiny.png" alt="Image" style="height: 64px" /><figcaption>This is 64 pixels high.</figcaption></figure>
       </div>
     </div>
   </div>

diff --git a/doxygen/test/contents_image/input.dox b/doxygen/test/contents_image/input.dox
index d34b32fe374550ad42bccc500282cc9a835cfdf1..736ce2a8642a561efd482f84405ca89cf756af13 100644 (file)
--- a/doxygen/test/contents_image/input.dox
+++ b/doxygen/test/contents_image/input.dox
@@ -8,6 +8,14 @@ Figure:
 
 @image html tiny.png Caption
 
+Explicit width:
+
+@image html tiny.png width=128px
+
+Explicit height and a caption:
+
+@image html tiny.png "This is 64 pixels high." height=64px
+
 */
 
 /** @page warnings Images that produce warnings