✨ NEW: add <img> tag parsing (#210)

Author: chrisjsewell

docs/conf.py

@@ -67,6 +67,7 @@
 
 myst_amsmath_enable = True
 myst_admonition_enable = True
+myst_html_img = True
 
 
 def run_apidoc(app):

docs/using/img/fun-fish.png

@@ -217,13 +217,16 @@ To do so, use the keywords beginning `myst_`.
 * - Option
   - Default
   - Description
+* - `myst_disable_syntax`
+  - ()
+  - List of markdown syntax elements to disable, see the [markdown-it parser guide](markdown_it:using).
 * - `myst_url_schemes`
   - `None`
   - [URI schemes](https://en.wikipedia.org/wiki/List_of_URI_schemes) that will be recognised as external URLs in `[](scheme:loc)` syntax, or set `None` to recognise all.
     Other links will be resolved as internal cross-references.
-* - `myst_disable_syntax`
-  - ()
-  - List of markdown syntax elements to disable, see the [markdown-it parser guide](markdown_it:using).
+* - `myst_html_img`
+  - `False`
+  - Convert HTML <img> elements to sphinx image nodes, see the [image syntax](syntax/images) for details
 * - `myst_math_delimiters`
   - "dollars"
   - Delimiters for parsing math, see the [Math syntax](syntax/math) for details

docs/using/intro.md

@@ -232,22 +232,22 @@ In addition to these summaries of inline syntax, see {ref}`extra-markdown-syntax
   - Description
   - Example
 * - HTMLSpan
-  - any valid HTML (rendered in HTML output only)
+  - Any valid HTML (rendered in HTML output only)
   - ```html
     <p>some text</p>
     ```
 * - EscapeSequence
-  - escaped symbols (to avoid them being interpreted as other syntax elements)
+  - Escaped symbols (to avoid them being interpreted as other syntax elements)
   - ```md
     \*
     ```
 * - AutoLink
-  - link that is shown in final output
+  - Link that is shown in final output
   - ```md
     <http://www.google.com>
     ```
 * - InlineCode
-  - literal text
+  - Literal text
   - ```md
     `a=1`
     ```
@@ -257,7 +257,8 @@ In addition to these summaries of inline syntax, see {ref}`extra-markdown-syntax
     A hard break\
     ```
 * - Image
-  - link to an image
+  - Link to an image.
+    You can also use HTML syntax, to include image size etc, [see here](syntax/images) for details
   - ```md
     ![alt](src "title")
     ```
@@ -267,17 +268,17 @@ In addition to these summaries of inline syntax, see {ref}`extra-markdown-syntax
     [text](target "title") or [text][key]
     ```
 * - Strong
-  - bold text
+  - Bold text
   - ```md
     **strong**
     ```
 * - Emphasis
-  - italic text
+  - Italic text
   - ```md
     *emphasis*
     ```
 * - RawText
-  - any text
+  - Any text
   - ```md
     any text
     ```
@@ -894,8 +895,58 @@ leave the "text" section of the markdown link empty. For example, this
 markdown: `[](syntax.md)` will result in: [](syntax.md).
 ```
 
-(syntax/footnotes)=
+(syntax/images)=
+
+### Images
+
+MyST provides a few different syntaxes for including images in your documentation, as explained below.
+
+The first is the standard Markdown syntax:
+
+```md
+![fishy](img/fun-fish.png)
+```
+
+![fishy](img/fun-fish.png)
+
+This will correctly copy the image to the build folder and will render it in all output formats (HTML, TeX, etc).
+However, it is limited in the configuration that can be applied, for example setting a width.
+
+As discussed [above](syntax/directives), MyST allow for directives to be used such as `image` and `figure` (see {ref}`the sphinx documentation <sphinx:rst-primer>`):
+
+````md
+```{image} img/fun-fish.png
+:alt: fishy
+:class: bg-primary
+:width: 200px
+:align: center
+```
+````
+
+```{image} img/fun-fish.png
+:alt: fishy
+:class: bg-primary mb-1
+:width: 200px
+```
+
+Additional options can now be set, however, in contrast to the Markdown syntax, this syntax will not show the image in common Markdown viewers (for example when the files are viewed on GitHub).
+
+The final option is directly using HTML, which is also parsed by MyST.
+This is usually a bad option, because the HTML is treated as raw text during the build process and so sphinx will not recognise that the image file is to be copied, and will not output the HTML into non-HTML output formats.
+
+HTML parsing to the rescue!
+By setting `myst_html_img = True` in the sphinx `conf.py` configuration file, MySt-Parser will attempt to convert any isolated `img` tags (i.e. not wrapped in any other HTML) to the internal representation used in sphinx.
 
+```md
+<img src="img/fun-fish.png" alt="fishy" class="bg-primary" width="200px">
+```
+
+<img src="img/fun-fish.png" alt="fishy" class="bg-primary mb-1" width="200px">
+
+Allowed attributes are equivalent to the `image` directive: src, alt, class, width, height and name.
+Any other attributes will be dropped.
+
+(syntax/footnotes)=
 ### Footnotes
 
 Footnote labels **start with `^`** and can then be any alpha-numeric string (no spaces),

docs/using/syntax.md

@@ -29,6 +29,7 @@ def setup_sphinx(app):
     app.add_config_value("myst_math_delimiters", "dollars", "env")
     app.add_config_value("myst_amsmath_enable", False, "env")
     app.add_config_value("myst_admonition_enable", False, "env")
+    app.add_config_value("myst_html_img", False, "env")
 
     app.connect("config-inited", validate_config)
 

myst_parser/__init__.py

@@ -33,6 +33,7 @@
     MockIncludeDirective,
 )
 from .parse_directives import parse_directive_text, DirectiveParsingError
+from .parse_html import HTMLImgParser
 
 
 def make_document(source_path="notset") -> nodes.document:
@@ -468,7 +469,12 @@ def render_html_inline(self, token):
         self.current_node.append(nodes.raw("", token.content, format="html"))
 
     def render_html_block(self, token):
-        self.current_node.append(nodes.raw("", token.content, format="html"))
+        node = None
+        if self.config.get("myst_html_img", False):
+            node = HTMLImgParser().parse(token.content, self.document, token.map[0])
+        if node is None:
+            node = nodes.raw("", token.content, format="html")
+        self.current_node.append(node)
 
     def render_image(self, token):
         img_node = nodes.image()

myst_parser/docutils_renderer.py

@@ -0,0 +1,70 @@
+from html.parser import HTMLParser
+from docutils import nodes
+
+from docutils.parsers.rst import directives
+
+
+class ExitImageParse(Exception):
+    pass
+
+
+def align(argument):
+    return directives.choice(argument, ("left", "center", "right"))
+
+
+def make_error(document, error_msg, text, line_number):
+    return document.reporter.error(
+        "<img> conversion: {}".format(error_msg),
+        nodes.literal_block(text, text),
+        line=line_number,
+    )
+
+
+class HTMLImgParser(HTMLParser):
+    def handle_starttag(self, tag, attrs):
+        if tag == "img":
+            self._attrs = dict(attrs)
+        raise ExitImageParse()
+
+    def parse(self, text: str, document: nodes.document, line_number: int):
+        self.reset()
+        self._attrs = None
+        try:
+            self.feed(text)
+        except ExitImageParse:
+            pass
+        if self._attrs is None:
+            return
+
+        # TODO check for preceding text?
+
+        if "src" not in self._attrs:
+            return make_error(document, "missing src attribute", text, line_number)
+
+        options = {}
+        for name, key, spec in [
+            ("src", "uri", directives.uri),
+            ("class", "classes", directives.class_option),
+            ("alt", "alt", directives.unchanged),
+            ("height", "height", directives.length_or_unitless),
+            ("width", "width", directives.length_or_percentage_or_unitless),
+            ("align", "align", align)
+            # note: docutils also has scale and target
+        ]:
+            if name in self._attrs:
+                value = self._attrs[name]
+                try:
+                    options[key] = spec(value)
+                except (ValueError, TypeError) as error:
+                    error_msg = "Invalid attribute: (key: '{}'; value: {})\n{}".format(
+                        name, value, error
+                    )
+                    return make_error(document, error_msg, text, line_number)
+
+        node = nodes.image(text, **options)
+        if "name" in self._attrs:
+            name = nodes.fully_normalize_name(self._attrs["name"])
+            node["names"].append(name)
+            document.note_explicit_target(node, node)
+
+        return node

myst_parser/parse_html.py

@@ -27,6 +27,7 @@ class MystParser(Parser):
         "myst_math_delimiters": "dollars",
         "myst_amsmath_enable": False,
         "myst_admonition_enable": False,
+        "myst_html_img": False,
     }
 
     # these specs are copied verbatim from the docutils RST parser
@@ -202,7 +203,12 @@ def get_markdown_parser(config: dict, renderer: str = "sphinx"):
             enable_amsmath=config["myst_amsmath_enable"],
             enable_admonitions=config["myst_admonition_enable"],
         )
-        parser.options.update({"myst_url_schemes": config["myst_url_schemes"]})
+        parser.options.update(
+            {
+                "myst_url_schemes": config["myst_url_schemes"],
+                "myst_html_img": config["myst_html_img"],
+            }
+        )
         return parser
 
 

myst_parser/sphinx_parser.py

@@ -0,0 +1,41 @@
+from unittest.mock import Mock
+import pytest
+
+from myst_parser.parse_html import HTMLImgParser
+
+
+@pytest.mark.parametrize("text", ["", "abc", "<div></div>" "<div><img></div>"])
+def test_html_parse_none(text):
+    document = Mock(reporter=Mock(error=Mock(return_value="error")))
+    output = HTMLImgParser().parse(text, document, 0)
+    assert output is None
+
+
+@pytest.mark.parametrize(
+    "text", ["<img>", '<img src="a" width="x">', '<img src="a" height="x">']
+)
+def test_html_parse_error(text):
+    document = Mock(reporter=Mock(error=Mock(return_value="error")))
+    output = HTMLImgParser().parse(text, document, 0)
+    assert output == "error"
+
+
+@pytest.mark.parametrize(
+    "text,outcome",
+    [
+        ('<img src="a">', '<image uri="a">'),
+        ('<img src="a" other="b">', '<image uri="a">'),
+        (
+            '<img src="a" height="200px" class="a b">',
+            '<image classes="a b" height="200px" uri="a">',
+        ),
+        (
+            '<img src="a" name="b" align="left">',
+            '<image align="left" names="b" uri="a">',
+        ),
+    ],
+)
+def test_html_parse_ok(text, outcome):
+    document = Mock(reporter=Mock(error=Mock(return_value="error")))
+    output = HTMLImgParser().parse(text, document, 0)
+    assert output.pformat().strip() == outcome