liran-funaro / sphinx-markdown-builder / 43210909330

100%

push

github

Escape image alt text and wrap link destinations when needed (#134)

## Summary

Image alt text and link or image destinations were written into
`![alt](uri)` / `[text](uri)` as they were, so a `]` in the alt text or
an unbalanced `(` in a URL produced broken Markdown.

- `visit_image` escapes `\`, `[` and `]` in the alt text.
- A new helper, `escape_link_destination` in `escape.py`, is used by
`visit_image`, `visit_reference` and `visit_download_reference`. It
wraps the destination in `<...>` (escaping `<`/`>` inside it) only when
the destination cannot be written bare: when it contains whitespace,
`<`, `>` or parentheses that are not balanced. Any other destination is
left as it is, so no existing golden output changed. Balanced
parentheses are recognized one level deep. A destination with deeper
nesting gets wrapped, which is still valid.

## Before / after

Input (added to `tests/source/image-target.rst`):

```rst
`Link with an unbalanced parenthesis <https://example.com/a_(b>`_.

`Link with balanced parentheses <https://example.com/a_(b)>`_.

.. image:: /static/markdown.png
   :alt: alt ] bracket
```

Before:

```markdown
[Link with an unbalanced parenthesis](https://example.com/a_(b).

[Link with balanced parentheses](https://example.com/a_(b)).

![alt ] bracket](static/markdown.png)
```

After:

```markdown
[Link with an unbalanced parenthesis](<https://example.com/a_(b>).

[Link with balanced parentheses](https://example.com/a_(b)).

![alt \] bracket](static/markdown.png)
```

The same lines appear in `overrides-image-target.markdown`.

## Checks

- `make lint`: black, flake8 and pylint pass (10.00/10)
- `make test`: diff test passes; pytest 15 passed, coverage 100%

Closes #123


### Follow-up commits
- The regexes in `escape.py` are now module-level constants after the
imports, the same as in the other modules. The alt-text `re.sub` that
was inline in `visit_image` moved to a new `escape.alt_text()`.
- Callers now import the `escape` module ... (continued)

19 of 19 new or added lines in 3 files covered. (100.0%)

806 of 806 relevant lines covered (100.0%)

4.0 hits per line