✨ NEW: Port abbr plugin (executablebooks#14)

[jessicah]

trafficstars

[welcome[bot]]

Thanks for submitting your first pull request! You are awesome! :hugs:
If you haven't done so already, check out EBP's Code of Conduct and our Contributing Guide, as this will greatly help the review process.
Welcome to the EBP community! :tada:

[jessicah]

Hmm, pre-commit seems broken due to https://github.com/PyCQA/isort/issues/2077? I certainly can't run it.

[chrisjsewell]

Thanks @jessicah, could you perhaps add some more test cases, e.g. interaction with other syntax elements: abbr definitions in lists, abbr references in link texts, ...

Looking at this now, one issue related to myst-parser I'd note, is that the extension is doing a "look-ahead" parse to find all the abbreviation definitions. This is pain in relation to nested parsing. For example:

```{note}
*[HTML]: HyperText Markup Language

HTML
```

HTML

Here, in MyST-Parser, the outer HTML would not be converted to an abbreviation, because at that point in the rendering, the inner contents of the note have not yet been parsed.

The "ideal" solution may be, to have the markdown-it plugin collect all the abbreviation definitions, but not do the replacement of the text. Then, after the text has been fully converted to sphinx/docutils nodes, and all the abbr definitions have been collected, run a sphinx/docutils transform to do all the find/replace replacements

[jessicah]

@chrisjsewell hmm, that's how the original plugin does the replacements, it's basically a 1:1 translation of the source, just some janky translation of their regex loop.

I don't really know enough to be able to adapt to a nested parsing model; I pretty much relied on comparing an existing JS <-> Python extension... if you have some guidance, that would help!

[codecov[bot]]

Codecov Report

Base: 92.67% // Head: 92.43% // Decreases project coverage by -0.25% :warning:

Coverage data is based on head (838f199) compared to base (4601e15). Patch coverage: 88.46% of modified lines in pull request are covered.

Additional details and impacted files

@@            Coverage Diff             @@
##           master      #63      +/-   ##
==========================================
- Coverage   92.67%   92.43%   -0.25%     
==========================================
  Files          29       32       +3     
  Lines        1679     1784     +105     
==========================================
+ Hits         1556     1649      +93     
- Misses        123      135      +12     

Flag	Coverage Δ
pytests	92.43% <88.46%> (-0.25%)	:arrow_down:

Flags with carried forward coverage won't be shown. Click here to find out more.

Impacted Files	Coverage Δ
mdit_py_plugins/abbr/index.py	88.34% <88.34%> (ø)
mdit_py_plugins/abbr/__init__.py	100.00% <100.00%> (ø)
mdit_py_plugins/__init__.py	100.00% <0.00%> (ø)

Help us with your feedback. Take ten seconds to tell us how you rate us. Have a feature suggestion? Share it here.

:umbrella: View full report at Codecov.
:loudspeaker: Do you have feedback about the report comment? Let us know in this issue.

[chrisjsewell]

if you have some guidance, that would help!

I think just for now, if you could add in an option to not make the replacements (i.e. just extract the definitions). Then we have the option to do this on the myst-parser side.

def abbr_plugin(md: MarkdownIt, replace = True):
    """Plugin ported from
    `markdown-it-abbr <https://github.com/markdown-it/markdown-it-abbr>`__.

    .. code-block:: md
            *[HTML]: HyperText Markup Language
    """

    md.block.ruler.before(
        "reference", "abbr_def", abbr_def, {"alt": ["paragraph", "reference"]}
    )
    if replace:
        md.core.ruler.after("linkify", "abbr_replace", abbr_replace)

and yeh also if you can add some more tests