fix: add required output_block_math(); add synopsis

[drmingdrmer]

Cause:

I found that it does not render block math.
The complain is about a missing function output_block_math() which is required by a Markdown instance.

My solution:

Thus I added a output_block_math() in a Markdown sub class.

Explain:

From the mistune.py I see that
Customized inline lexer rendering functions are meant to be defined in a sub class of Renderer. But block level lexer rendering functions must be defined in a sub class of Markdown.

I do not know if I missed anything about the entire workflow or if there is another elegant way to fix it.

In order to let tests pass, lepture/mistune#185 must be applied first.

BTW. mistune is such a great work that saved me a lot time processing my own markdowns. 👍👍

[lepture]

You can create a test case for it. Don't add the tests here.

[drmingdrmer]

Well, another issue is that the following codes in mistune_contrib.math modifies a global variable default_rules.
Thus enable_math() breaks all other tests.

    def enable_math(self):
        self.rules.block_math = re.compile(r'^\$\$(.*?)\$\$', re.DOTALL)
        self.rules.block_latex = re.compile(
            r'^\\begin\{([a-z]*\*?)\}(.*?)\\end\{\1\}', re.DOTALL
        )
        self.default_rules.extend(['block_math', 'block_latex']) # <---

Where default_rules is defined, it's a variable shared by all BlockLexer isntance:

class BlockLexer(object):
    """Block level lexer for block grammars."""
    grammar_class = BlockGrammar

    default_rules = [
        'newline', 'hrule', 'block_code', 'fences', 'heading',
        'nptable', 'lheading', 'block_quote',
        'list_block', 'block_html', 'def_links',
        'def_footnotes', 'table', 'paragraph', 'text'
    ]

[drmingdrmer]

In order to let the test for math to pass, this pr must be applied first: lepture/mistune#185

[drmingdrmer]

hi @lepture what do think about these tests I provided in the last commit? 😃

[lepture]

But, please remove the code under __main__ (included)

[drmingdrmer]

I added these code as a complete guide of how to use contrib.math.
Because I did not find any sample codes in either mistune or mistune-contrib.

I did spend some time figuring out how to use it. I'd like these sample codes would save other's time.

If it is not appropriate leaving it in the if-main block, what's your suggestion about where to have it?

[lepture]

It is better in the doc strings.

currently, mistune is hard to extend. I'm working on mistune 2.0 which is easier to write plugins.

[drmingdrmer]

OK that