1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
|
#!/usr/bin/env python3
# :Copyright: © 2020 Günter Milde.
# :License: Released under the terms of the `2-Clause BSD license`_, in short:
#
# Copying and distribution of this file, with or without modification,
# are permitted in any medium without royalty provided the copyright
# notice and this notice are preserved.
# This file is offered as-is, without any warranty.
#
# .. _2-Clause BSD license: https://opensource.org/licenses/BSD-2-Clause
#
# Revision: $Revision: 9043 $
# Date: $Date: 2022-03-11 13:09:16 +0100 (Fr, 11. Mär 2022) $
"""
A parser for CommonMark Markdown text using `recommonmark`__.
__ https://pypi.org/project/recommonmark/
.. important:: This module is provisional
* The "recommonmark" package is unmaintained and deprecated.
This wrapper module will be removed in a future Docutils version.
* The API is not settled and may change with any minor Docutils version.
"""
from docutils import nodes, Component
try:
from recommonmark.parser import CommonMarkParser
except ImportError as err:
raise ImportError(f'{err}.\n'
'Parsing "recommonmark" Markdown flavour requires the '
'package https://pypi.org/project/recommonmark which '
'in turn depends on https://pypi.org/project/sphinx.')
try:
from sphinx import addnodes
# already cached in `sys.modules` if recommonmark >= 0.5.0
except ImportError:
# stub to prevent errors with recommonmark < 0.5.0
class addnodes:
pending_xref = nodes.pending
# auxiliary function for `document.findall()`
def is_literal(node):
return isinstance(node, (nodes.literal, nodes.literal_block))
class Parser(CommonMarkParser):
"""MarkDown parser based on recommonmark.
This parser is provisional:
the API is not settled and may change with any minor Docutils version.
"""
supported = ('recommonmark', 'commonmark', 'markdown', 'md')
"""Formats this parser supports."""
config_section = 'recommonmark parser'
config_section_dependencies = ('parsers',)
def get_transforms(self):
return Component.get_transforms(self) # + [AutoStructify]
def parse(self, inputstring, document):
"""Use the upstream parser and clean up afterwards.
"""
# check for exorbitantly long lines
for i, line in enumerate(inputstring.split('\n')):
if len(line) > document.settings.line_length_limit:
error = document.reporter.error(
'Line %d exceeds the line-length-limit.'%(i+1))
document.append(error)
return
# pass to upstream parser
try:
CommonMarkParser.parse(self, inputstring, document)
except Exception as err:
if document.settings.traceback:
raise err
error = document.reporter.error('Parsing with "recommonmark" '
'returned the error:\n%s'%err)
document.append(error)
# Post-Processing
# ---------------
# merge adjoining Text nodes:
for node in document.findall(nodes.TextElement):
children = node.children
i = 0
while i+1 < len(children):
if (isinstance(children[i], nodes.Text)
and isinstance(children[i+1], nodes.Text)):
children[i] = nodes.Text(children[i]+children.pop(i+1))
children[i].parent = node
else:
i += 1
# add "code" class argument to literal elements (inline and block)
for node in document.findall(is_literal):
if 'code' not in node['classes']:
node['classes'].append('code')
# move "language" argument to classes
for node in document.findall(nodes.literal_block):
if 'language' in node.attributes:
node['classes'].append(node['language'])
del node['language']
# replace raw nodes if raw is not allowed
if not document.settings.raw_enabled:
for node in document.findall(nodes.raw):
warning = document.reporter.warning('Raw content disabled.')
node.parent.replace(node, warning)
# drop pending_xref (Sphinx cross reference extension)
for node in document.findall(addnodes.pending_xref):
reference = node.children[0]
if 'name' not in reference:
reference['name'] = nodes.fully_normalize_name(
reference.astext())
node.parent.replace(node, reference)
def visit_document(self, node):
"""Dummy function to prevent spurious warnings.
cf. https://github.com/readthedocs/recommonmark/issues/177
"""
pass
# Overwrite parent method with version that
# doesn't pass deprecated `rawsource` argument to nodes.Text:
def visit_text(self, mdnode):
self.current_node.append(nodes.Text(mdnode.literal))
|
