search

executablebooks / MyST-Parser

An extended commonmark compliant parser, with bridges to docutils/sphinx
https://myst-parser.readthedocs.io
MIT License
756 stars 197 forks source link

parse method for custom roles (implement MockInliner.parse) #214

Open matthew-brett opened 4 years ago

matthew-brett commented 4 years ago

I really miss the parse method of the inliner object available within roles : https://github.com/executablebooks/MyST-Parser/blob/dcbd5ef/myst_parser/mocking.py#L46

It's very nice to be able to use Python / Sphinx code to extend Markdown with roles, but, without the parse method, it means I have to do a lot of hand-building with docutils / Sphinx nodes, in order do a fairly simple macro-like insertion:

https://github.com/matthew-brett/cfd2020/blob/2d15c9f/cfdcode/ucb_page.py#L91

Here, what I really wanted to do was something like:

nodes = inliner.parse("""\
This page has content from the [%s](%s) notebook of an older version of the 
UC Berkeley data science course. See {ref}`ucb-license`.""" % (text, url)

but I don't think there's any simple way to get the parsing machinery, in order do that. In particular, making the pending reference node at the end is extremely fiddly, so I gave up and made a hardish-coded URL.

If that was available it would have made my life a lot easier, and I think it would also make it possible to make a nice helper for simple custom roles, along the lines of the code I was working on here.

welcome[bot] commented 4 years ago

Thanks for opening your first issue here! Engagement like this is essential for open source projects! :hugs:
If you haven't done so already, check out EBP's Code of Conduct. Also, please try to follow the issue template as it helps other community members to contribute more effectively.
If your issue is a feature request, others may react to it, to raise its prominence (see Feature Voting).
Welcome to the EBP community! :tada:

chrisjsewell commented 4 years ago

As you can see its on the TODO list, I just hadn't found a role that required it yet 😄 I'll bump it up the priority list 👍

matthew-brett commented 4 years ago

Thanks.

On reflection - I wonder whether it would be worth having a parse and a parse_md method - so the role can be used with ReST as well as Markdown? Likewise for the directives?