search

miyuchina / mistletoe

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

Add missing documentation (#122) #123

Closed pbodnar closed 2 years ago

pbodnar commented 2 years ago

Note: I have focused just on the documentation here in the end.

not-my-profile commented 2 years ago

Important: The parsing phase is currently tightly connected with initiation and closing of a renderer. Therefore, you should never call Document(...) outside of a with ... as renderer block, unless you know what you are doing.

I think it would help to give an example of this "tight connection". Because just by reading that warning I have no idea.

I would like to parse a Markdown document into an AST, then do some processing on the AST and then render the resulting AST into HTML. Is that something that mistletoe can be used for or not?

pbodnar commented 2 years ago

@not-my-profile, thanks for your feedback -> see the new commit above - I hope it covers the topic of "tight connection" good enough now?

Regarding your second question, I think this should be possible. Something like:

with open('foo.md', 'r') as fin:
    with HTMLRenderer() as renderer:
        doc = Document(fin)
        # ... do some stuff with the doc ...
        rendered = renderer.render(doc)

Can you try out and let me know if it works for you?

pbodnar commented 2 years ago

OK, so I've pushed the doc commit to master. Feel free to open new issue / PR for improvements. :)

not-my-profile commented 2 years ago

Thanks for replying / clarifying!

I guess one of the reasons I find the API confusing is that Document(..) doesn't look like it's parsing. I wouldn't expect Document.__init__ to perform parsing.

pbodnar commented 2 years ago

OK, so here we go (8447a42). @not-my-profile, thanks for your feedback! :)