mistletoe
mistletoe copied to clipboard
Make renderers from the "contrib" folder easier to use
From my point of view, there are currently two gotchas about the "contrib" folder:
- If one just installs mistletoe by running
pip install mistletoe
(orpip install .
after Git cloning), the renderers from the "contrib" folder are not available when running mistletoe from any location. Unless one clones the Git repo and passes full (relative) path to a renderer. (I tried to describe this in this commit.) - The purpose of the whole "contrib" folder is kinda fuzzy. Apart from the various renderers that I suspect are probably a "contributed" unfinished work (see for example #100), there is also for example
md2jira.py
- how does this script fit to the concept of having the main mistletoe cli script that can do all the necessary stuff?
Here are some suggestions:
- Would it be possible to document the purpose of the "contrib" folder and how to work with it?
- What about moving the "contrib" folder, or at least renderers from there, to the "mistletoe" folder (where the other "core" renderers reside), or to make a subfolder within it, so that the renderers get available when mistletoe gets installed (not only when "installed" for developing purposes, i. e. by running
pip install -e .
)? Or maybe to have a special module "mistletoe_contrib" next to the existing "mistletoe" module (in the project's root folder) and add some installation scripts for it?
Note: I'm relatively new to Python and this "module / package bundling", so it is quite possible I have overlooked some easier way, I will be glad if someone shows me...
For the beginning, I have at least tried to document this: 86fe3a87b4d80d596b773c9e50aa6c2b5c4aa826 (actually merged my own commit from the issue description).
Hey @pbodnar, I found this article which explains pretty nicely how some popular open source software packages use the contrib folder.
I think your suggestion to move the contrib folder to become a subfolder within the mistletoe folder is good. That's how Django does it. The big advantage, as I see it, is that it makes the tools in contrib available as part of the regular pip package.
I can put up a PR for this if you like.
@anderskaplan, thanks for your feedback on this (the only feedback so far actually ;)). If you have time, it would be great if you prepare a PR. :)
PR created
And the PR resolved it. :)