Mercurial > repos > shellac > guppy_basecaller

comparison env/lib/python3.7/site-packages/mistune-0.8.4.dist-info/DESCRIPTION.rst @ 0:26e78fe6e8c4 draft

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
"planemo upload commit c699937486c35866861690329de38ec1a5d9f783"
author shellac
date Sat, 02 May 2020 07:14:21 -0400
parents
children
comparison
equal deleted inserted replaced
-1:000000000000 0:26e78fe6e8c4
1 Mistune
2 =======
3
4 The fastest markdown parser in pure Python with renderer features,
5 inspired by marked_.
6
7 .. image:: https://img.shields.io/badge/donate-lepture-green.svg
8 :target: https://lepture.com/donate
9 :alt: Donate lepture
10 .. image:: https://img.shields.io/pypi/wheel/mistune.svg?style=flat
11 :target: https://pypi.python.org/pypi/mistune/
12 :alt: Wheel Status
13 .. image:: https://anaconda.org/conda-forge/mistune/badges/version.svg
14 :target: https://anaconda.org/conda-forge/mistune
15 :alt: Conda Version
16 .. image:: https://img.shields.io/pypi/v/mistune.svg
17 :target: https://pypi.python.org/pypi/mistune/
18 :alt: Latest Version
19 .. image:: https://travis-ci.org/lepture/mistune.svg?branch=master
20 :target: https://travis-ci.org/lepture/mistune
21 :alt: Travis CI Status
22 .. image:: https://coveralls.io/repos/lepture/mistune/badge.svg?branch=master
23 :target: https://coveralls.io/r/lepture/mistune
24 :alt: Coverage Status
25 .. image:: https://ci.appveyor.com/api/projects/status/8ai8tfwp75oela17?svg=true
26 :target: https://ci.appveyor.com/project/lepture/mistune
27 :alt: App Veyor CI Status
28
29 .. _marked: https://github.com/chjj/marked
30
31
32 Features
33 --------
34
35 * **Pure Python**. Tested in Python 2.7, Python 3.5+ and PyPy.
36 * **Very Fast**. It is the fastest in all **pure Python** markdown parsers.
37 * **More Features**. Table, footnotes, autolink, fenced code etc.
38
39 View the `benchmark results <https://github.com/lepture/mistune/issues/1>`_.
40
41 Installation
42 ------------
43
44 Installing mistune with pip::
45
46 $ pip install mistune
47
48
49 Mistune can be faster, if you compile with cython::
50
51 $ pip install cython mistune
52
53
54 Basic Usage
55 -----------
56
57 A simple API that render a markdown formatted text:
58
59 .. code:: python
60
61 import mistune
62
63 mistune.markdown('I am using **mistune markdown parser**')
64 # output: <p>I am using <strong>mistune markdown parser</strong></p>
65
66 If you care about performance, it is better to re-use the Markdown instance:
67
68 .. code:: python
69
70 import mistune
71
72 markdown = mistune.Markdown()
73 markdown('I am using **mistune markdown parser**')
74
75 Mistune has enabled all features by default. You don't have to configure
76 anything. But there are options for you to change the parser behaviors.
77
78
79 Options
80 -------
81
82 Here is a list of all options that will affect the rendering results,
83 configure them with ``mistune.Renderer``:
84
85 .. code:: python
86
87 renderer = mistune.Renderer(escape=True, hard_wrap=True)
88 # use this renderer instance
89 markdown = mistune.Markdown(renderer=renderer)
90 markdown(text)
91
92 * **escape**: if set to *False*, all raw html tags will not be escaped.
93 * **hard_wrap**: if set to *True*, it will has GFM line breaks feature.
94 All new lines will be replaced with ``<br>`` tag
95 * **use_xhtml**: if set to *True*, all tags will be in xhtml, for example: ``<hr />``.
96 * **parse_block_html**: parse text only in block level html.
97 * **parse_inline_html**: parse text only in inline level html.
98
99 When using the default renderer, you can use one of the following shortcuts::
100
101 mistune.markdown(text, escape=True, hard_wrap=True)
102
103 markdown = mistune.Markdown(escape=True, hard_wrap=True)
104 markdown(text)
105
106
107 Renderer
108 --------
109
110 Like misaka/sundown, you can influence the rendering by custom renderers.
111 All you need to do is subclassing a `Renderer` class.
112
113 Here is an example of code highlighting:
114
115 .. code:: python
116
117 import mistune
118 from pygments import highlight
119 from pygments.lexers import get_lexer_by_name
120 from pygments.formatters import html
121
122 class HighlightRenderer(mistune.Renderer):
123 def block_code(self, code, lang):
124 if not lang:
125 return '\n<pre><code>%s</code></pre>\n' % \
126 mistune.escape(code)
127 lexer = get_lexer_by_name(lang, stripall=True)
128 formatter = html.HtmlFormatter()
129 return highlight(code, lexer, formatter)
130
131 renderer = HighlightRenderer()
132 markdown = mistune.Markdown(renderer=renderer)
133 print(markdown('```python\nassert 1 == 1\n```'))
134
135 Find more renderers in `mistune-contrib`_.
136
137 Block Level
138 ~~~~~~~~~~~
139
140 Here is a list of block level renderer API::
141
142 block_code(code, language=None)
143 block_quote(text)
144 block_html(html)
145 header(text, level, raw=None)
146 hrule()
147 list(body, ordered=True)
148 list_item(text)
149 paragraph(text)
150 table(header, body)
151 table_row(content)
152 table_cell(content, **flags)
153
154 The *flags* tells you whether it is header with ``flags['header']``. And it
155 also tells you the align with ``flags['align']``.
156
157
158 Span Level
159 ~~~~~~~~~~
160
161 Here is a list of span level renderer API::
162
163 autolink(link, is_email=False)
164 codespan(text)
165 double_emphasis(text)
166 emphasis(text)
167 image(src, title, alt_text)
168 linebreak()
169 newline()
170 link(link, title, content)
171 strikethrough(text)
172 text(text)
173 inline_html(text)
174
175 Footnotes
176 ~~~~~~~~~
177
178 Here is a list of renderers related to footnotes::
179
180 footnote_ref(key, index)
181 footnote_item(key, text)
182 footnotes(text)
183
184 Lexers
185 ------
186
187 Sometimes you want to add your own rules to Markdown, such as GitHub Wiki
188 links. You can't achieve this goal with renderers. You will need to deal
189 with the lexers, it would be a little difficult for the first time.
190
191 We will take an example for GitHub Wiki links: ``[[Page 2|Page 2]]``.
192 It is an inline grammar, which requires custom ``InlineGrammar`` and
193 ``InlineLexer``:
194
195 .. code:: python
196
197 import copy,re
198 from mistune import Renderer, InlineGrammar, InlineLexer
199
200 class WikiLinkRenderer(Renderer):
201 def wiki_link(self, alt, link):
202 return '<a href="%s">%s</a>' % (link, alt)
203
204 class WikiLinkInlineLexer(InlineLexer):
205 def enable_wiki_link(self):
206 # add wiki_link rules
207 self.rules.wiki_link = re.compile(
208 r'\[\[' # [[
209 r'([\s\S]+?\|[\s\S]+?)' # Page 2|Page 2
210 r'\]\](?!\])' # ]]
211 )
212
213 # Add wiki_link parser to default rules
214 # you can insert it some place you like
215 # but place matters, maybe 3 is not good
216 self.default_rules.insert(3, 'wiki_link')
217
218 def output_wiki_link(self, m):
219 text = m.group(1)
220 alt, link = text.split('|')
221 # you can create an custom render
222 # you can also return the html if you like
223 return self.renderer.wiki_link(alt, link)
224
225 You should pass the inline lexer to ``Markdown`` parser:
226
227 .. code:: python
228
229 renderer = WikiLinkRenderer()
230 inline = WikiLinkInlineLexer(renderer)
231 # enable the feature
232 inline.enable_wiki_link()
233 markdown = Markdown(renderer, inline=inline)
234 markdown('[[Link Text|Wiki Link]]')
235
236 It is the same with block level lexer. It would take a while to understand
237 the whole mechanism. But you won't do the trick a lot.
238
239
240 Contribution & Extensions
241 -------------------------
242
243 Mistune itself doesn't accept any extension. It will always be a simple one
244 file script.
245
246 If you want to add features, you can head over to `mistune-contrib`_.
247
248 Here are some extensions already in `mistune-contrib`_:
249
250 * Math/MathJax features
251 * Highlight Code Renderer
252 * TOC table of content features
253 * MultiMarkdown Metadata parser
254
255 Get inspired with the contrib repository.
256
257 .. _`mistune-contrib`: https://github.com/lepture/mistune-contrib
258
259