Open abravalheri opened 2 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:
Heya, yeh I have to admit, I hadn't noticed the "links with substitutions" syntax before, and never used it in my own work.
Your proposed solutions both seem viable, thanks.
Maybe I would lean towards expected_option1
, as you end up with less verbose Markdown. But probably I would err towards replacing space with __
rather than _
, just to make it slightly less likely there would be key clashes.
I can't say I have time right now to do this myself 😬 but would certainly welcome any PRs
Also interested to have a look at pyscaffold!
Thank you very much @chrisjsewell.
I am more or less in the same boat here in terms of time for contributing 😝, but in the future if I manage to get my hands on rst-to-myst
, do you have any tips from where to start for this issue? (I am not familiar with the codebase...)
I have been using PyScaffold for years in a row now and I am really satisfied on how it helps me to creates Python packages (so much that I became one of the maintainers).
Lately I have been trying to integrate rst-to-myst
so we can provide a out-of-the-box experience for people that want to write documentation in Markdown. The idea is to have an extension that translate our default .rst
templates to MyST-markdown.
Let me know if you want to some information about PyScaffold, I am more than happy to chat about it 😄
Describe the problem
The way
rst2myst
translates rst substitutions to Markdown does not seem to work properly. So far 2 inconsistencies have been identified:rst2myst
relies on MyST ability to use Jinja2 for substitutions. However Jinja2 requires a valid identifier (i.e., valid Python variable names), which is a much more restrictive condition, and therefore not compatible withrst
(e.g.rst
accepts strings with spaces)rst2myst
fails on translating links with substitutions (e.g.|ref|_
), which are a very common use case when writingrst
(e.g. for creating links with bold, italic or monospaced text elements)This issue was first identified in pyscaffold/pyscaffoldext-markdown#25. A simplified description of the problem and steps to reproduce it can be found in this gist.
Link to your repository or website
https://gist.github.com/abravalheri/a9cdfa09f2809182fccca659b413da4a
Steps to reproduce
The following is a simplified example to reproduce the problem:
Assuming I have the following (example) in ReStructuredText:
When I try to convert it using the CLI (
rst2myst stream original.rst > converted.md
), I obtain the following MyST-flavoured markdown:git push -u origin my-feature
As we can see, converted markdown contains invalid Jinja2 syntax, e.g.
{{ the repository service }}
, and the original link with substitution was converted to a simple link, without a substitution.The version of Python you're using
3.8.0
Your operating system
Ubuntu 18.04.5 LTS
Versions of your packages
Direct installation:
The remaining packages where installed as dependencies of those 3 in an empty virtual environment created with:
Expected output
Two different behaviours could be expected from
rst2myst
:|the repository service|
could be translated to{{ the_repository_service }}
. This approach in shown inexpected_option1
bellow.__
), e.g.|the repository service|
could be translated to{{ __["the repository service"] }}
. This approach in shown inexpected_option2
bellowRegarding links with substitutions, CommonMark's full reference links in combination with Jinja2 seem to be a good alternative, e.g.
|ref|_
could be translated to[{{ ref }}][ref]
. This approach is shown in bothexpected_option1
andexpected_option2
.expected_option1
expected_option2
In
expected_option2
, instead of using a nested dict__
inside ofsubstitutions
, thesubstititions
dict itself could also be directly assigned to__
in the Jinja2 template context, this would allow users using any substitution key directly if they are valid identifiers and invalid identifiers via the__
helper.(code blocks around
git push ...
inexpected_option1|2
omitted due to GitHub's inability of dealing with nested code blocks)