From: Vladimír Vondruš <mosra@centrum.cz>
Date: Sun, 7 Oct 2018 11:11:16 +0000 (+0200)
Subject: doxygen: support specifying explicit image width/height.
X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~cjwatson/git?a=commitdiff_plain;h=75da75fe6d0217fe1901d305a2e723ee7001192d;p=blog.git

doxygen: support specifying explicit image width/height.
---

diff --git a/doc/doxygen.rst b/doc/doxygen.rst
index 7129da3a..ccacbb76 100644
--- 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 602f6c25..20211cea 100755
--- 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 738cbbca..93394d5b 100644
--- 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 d34b32fe..736ce2a8 100644
--- 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