search

miyuchina / mistletoe

A fast, extensible and spec-compliant Markdown parser in pure Python.
MIT License
841 stars 119 forks source link

Make renderers from the "contrib" folder easier to use #101

Closed pbodnar closed 1 year ago

pbodnar commented 4 years ago

From my point of view, there are currently two gotchas about the "contrib" folder:

  1. If one just installs mistletoe by running pip install mistletoe (or pip 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.)
  2. 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:

  1. Would it be possible to document the purpose of the "contrib" folder and how to work with it?
  2. 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...

pbodnar commented 2 years ago

For the beginning, I have at least tried to document this: 86fe3a87b4d80d596b773c9e50aa6c2b5c4aa826 (actually merged my own commit from the issue description).

anderskaplan commented 2 years ago

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.

pbodnar commented 2 years ago

@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. :)

anderskaplan commented 1 year ago

PR created

pbodnar commented 1 year ago

And the PR resolved it. :)