From: Vladimír Vondruš Date: Thu, 7 Dec 2017 01:03:06 +0000 (+0100) Subject: doxygen: rework image support. X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~cjwatson/git?a=commitdiff_plain;h=b2dae3bd4a95305fa1400bc10f006d64d148990f;p=blog.git 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 0696f9e7..0b7fb43f 100644 --- 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:`

` 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. + +.. 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 d408ef86..58999de7 100755 --- 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 += '{}'.format(name, html.escape(alt)) + caption = i.text + if caption: + out.parsed += '

Image
{}
'.format(name, html.escape(caption)) + else: + out.parsed += '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 3a0965ec..b914e0d1 100644 --- a/doxygen/test/contents_image/index.html +++ b/doxygen/test/contents_image/index.html @@ -37,7 +37,7 @@

My Project

-Alt text +

Image:

Image

Figure:

Image
Caption
diff --git a/doxygen/test/contents_image/input.dox b/doxygen/test/contents_image/input.dox index 0c5c1576..d34b32fe 100644 --- 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 769ce803..f624aa2f 100644 --- a/doxygen/test/contents_image/warnings.html +++ b/doxygen/test/contents_image/warnings.html @@ -37,7 +37,7 @@

Images that produce warnings

-Image that doesn't exist.

Image without alt text:

Image +

Image that doesn't exist:

Image diff --git a/doxygen/test/test_doxyfile.py b/doxygen/test/test_doxyfile.py index f492bff1..8e1a29b6 100644 --- 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,