doxygen: rework image support.

 * The text after is not an alt text, but rather a figure caption. So
   render a figure in that case.
 * That means it's also not an error if the caption is not present. So
   don't warn about it.
 * Doxygen, if it wouldn't be so broken, would copy the images to the
   XML output directory as well. So there's no need to juggle with
   IMAGE_PATH. I love the smell of burning code.

diff --git a/doc/doxygen.rst b/doc/doxygen.rst
index 0696f9e7b939a6973b6fb0fa937517da50f48105..0b7fb43f17c7f88850fc214b68d51d04fd092831 100644 (file)
--- a/doc/doxygen.rst
+++ b/doc/doxygen.rst
@@ -210,8 +210,6 @@ Variable                        Description
 :ini:`HTML_OUTPUT`              The output will be written here
 :ini:`TAGFILES`                 Used to discover what base URL to prepend to
                                 external references
-:ini:`IMAGE_PATHS`              Used to discover where Doxygen gets the image
-                                files
 :ini:`HTML_EXTRA_STYLESHEET`    List of CSS files to include. Relative paths
                                 are also searched relative to the
                                 ``dox2html5.py`` script. See below for more
@@ -292,8 +290,8 @@ place of ``m-light+doxygen.compiled.css``:
 See the `CSS files`_ section below for more information about customizing the
 CSS files.
 
-`Text content`_
-===============
+`Content`_
+==========
 
 Brief and detailed description is parsed as-is with the following
 modifications:
@@ -353,6 +351,14 @@ single-paragraph item will make sure the enclosing :html:`<p>` is not stripped.
           </li>
         </ul>
 
+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.
+
+.. block-warning:: Doxygen patches
+
+    Current stable release of Doxygen has broken copying of images for the XML
+    output. You need to apply :gh:`doxygen/doxygen#629` in order to fix that.
+
 `Pages, sections and table of contents`_
 ========================================
 

diff --git a/doxygen/dox2html5.py b/doxygen/dox2html5.py
index d408ef867beb514fc400dfe645cb492545769626..58999de766d730e712a2c31498d07c85519cdac5 100755 (executable)
--- a/doxygen/dox2html5.py
+++ b/doxygen/dox2html5.py
@@ -541,24 +541,19 @@ def parse_desc_internal(state: State, element: ET.Element, immediate_parent: ET.
         elif i.tag == 'image':
             has_block_elements = True
             name = i.attrib['name']
-            path = None
 
             if i.attrib['type'] == 'html':
-                # Discover the real path of the image
-                for candidate in state.doxyfile['IMAGE_PATH']:
-                    path = os.path.join(state.basedir, candidate, name)
-                    if os.path.exists(path):
-                        state.images += [path]
-                        break
+                path = os.path.join(state.basedir, state.doxyfile['OUTPUT_DIRECTORY'], state.doxyfile['XML_OUTPUT'], name)
+                if os.path.exists(path):
+                    state.images += [path]
                 else:
-                    logging.warning("Image {} was not found in any IMAGE_PATH".format(name))
+                    logging.warning("Image {} was not found in XML_OUTPUT".format(name))
 
-                alt = i.text
-                if not alt:
-                    alt = 'Image'
-                    logging.warning("Image {} has no alt text".format(name))
-
-                out.parsed += '<img class="m-image" src="{}" alt="{}" />'.format(name, html.escape(alt))
+                caption = i.text
+                if caption:
+                    out.parsed += '<figure class="m-figure"><img src="{}" alt="Image" /><figcaption>{}</figcaption></figure>'.format(name, html.escape(caption))
+                else:
+                    out.parsed += '<img class="m-image" src="{}" alt="Image" />'.format(name)
 
         # Either block or inline because DOXYGEN!!! WHAT!!!
         elif i.tag == 'formula':
@@ -1541,7 +1536,6 @@ def parse_doxyfile(state: State, doxyfile, config = None):
         'OUTPUT_DIRECTORY': [''],
         'XML_OUTPUT': ['xml'],
         'HTML_OUTPUT': ['html'],
-        'IMAGE_PATH': [],
         'HTML_EXTRA_STYLESHEET': [
             'https://fonts.googleapis.com/css?family=Source+Sans+Pro:400,400i,600,600i%7CSource+Code+Pro:400,400i,600',
             '../css/m-dark+doxygen.compiled.css'],
@@ -1636,7 +1630,6 @@ def parse_doxyfile(state: State, doxyfile, config = None):
 
     # List values that we want. Drop empty lines.
     for i in ['TAGFILES',
-              'IMAGE_PATH',
               'HTML_EXTRA_STYLESHEET',
               'HTML_EXTRA_FILES']:
         if i in config:

diff --git a/doxygen/test/contents_image/index.html b/doxygen/test/contents_image/index.html
index 3a0965ec23194e42028bcfb51977034fd12c8612..b914e0d1c81477485d56d3ba3519abc0b5d3e822 100644 (file)
--- a/doxygen/test/contents_image/index.html
+++ b/doxygen/test/contents_image/index.html
@@ -37,7 +37,7 @@
         <h1>
           My Project
         </h1>
-<img class="m-image" src="tiny.png" alt="Alt text" />
+<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>
       </div>
     </div>
   </div>

diff --git a/doxygen/test/contents_image/input.dox b/doxygen/test/contents_image/input.dox
index 0c5c1576d51b81dadac7db2bffbcf10e4fefef68..d34b32fe374550ad42bccc500282cc9a835cfdf1 100644 (file)
--- a/doxygen/test/contents_image/input.dox
+++ b/doxygen/test/contents_image/input.dox
@@ -1,15 +1,19 @@
 /** @mainpage
 
-@image html tiny.png Alt text
+Image:
+
+@image html tiny.png
+
+Figure:
+
+@image html tiny.png Caption
 
 */
 
 /** @page warnings Images that produce warnings
 
-@image html nonexistent.png Image that doesn't exist.
-
-Image without alt text:
+Image that doesn't exist:
 
-@image html tiny.png
+@image html nonexistent.png
 
 */

diff --git a/doxygen/test/contents_image/warnings.html b/doxygen/test/contents_image/warnings.html
index 769ce8031c0e454646fdd8058c9c38ea9650e0c0..f624aa2f1f24c851c42837c8f1ef54d7396de0c1 100644 (file)
--- a/doxygen/test/contents_image/warnings.html
+++ b/doxygen/test/contents_image/warnings.html
@@ -37,7 +37,7 @@
         <h1>
           Images that produce warnings
         </h1>
-<img class="m-image" src="nonexistent.png" alt="Image that doesn&#x27;t exist." /><p>Image without alt text:</p><img class="m-image" src="tiny.png" alt="Image" />
+<p>Image that doesn&#x27;t exist:</p><img class="m-image" src="nonexistent.png" alt="Image" />
       </div>
     </div>
   </div>

diff --git a/doxygen/test/test_doxyfile.py b/doxygen/test/test_doxyfile.py
index f492bff1bb8f4a24f29f2212be5d4d0809d727f1..8e1a29b687435e0d96d8927b3eb0e0069cab28db 100644 (file)
--- a/doxygen/test/test_doxyfile.py
+++ b/doxygen/test/test_doxyfile.py
@@ -10,7 +10,6 @@ class Doxyfile(unittest.TestCase):
             'HTML_EXTRA_FILES': ['css', 'another.png', 'hello'],
             'HTML_EXTRA_STYLESHEET': ['a.css', 'b.css'],
             'HTML_OUTPUT': 'html',
-            'IMAGE_PATH': [],
             'M_CLASS_TREE_EXPAND_LEVELS': 1,
             'M_EXPAND_INNER_TYPES': 0,
             'M_FILE_TREE_EXPAND_LEVELS': 1,