solidity/docs/ext/remix_code_links.py

84 lines
3.1 KiB
Python
Raw Normal View History

import base64
import docutils # pragma pylint: disable=import-error
from sphinx.util import logging # pragma pylint: disable=import-error
# NOTE: 2000 should generally be safe for all browsers, while 8000 for most of them.
MAX_SAFE_URL_LENGTH = 10000
logger = logging.getLogger(__name__)
def insert_node_before(child, new_sibling):
assert child in child.parent.children
for position, node in enumerate(child.parent.children):
if node == child:
child.parent.insert(position, new_sibling)
break
def remix_code_url(source_code, language, solidity_version):
# NOTE: base64 encoded data may contain +, = and / characters. Remix seems to handle them just
# fine without any escaping.
base64_encoded_source = base64.b64encode(source_code.encode('utf-8')).decode('ascii')
return f"https://remix.ethereum.org/?language={language}&version={solidity_version}&code={base64_encoded_source}"
def build_remix_link_node(url):
link_icon_node = docutils.nodes.inline()
link_icon_node.set_class('link-icon')
link_text_node = docutils.nodes.inline(text="open in Remix")
link_text_node.set_class('link-text')
reference_node = docutils.nodes.reference('', '', internal=False, refuri=url)
reference_node.set_class('remix-link')
reference_node += [link_icon_node, link_text_node]
paragraph_node = docutils.nodes.paragraph()
paragraph_node.set_class('remix-link-container')
paragraph_node += reference_node
return paragraph_node
def insert_remix_link(app, doctree, solidity_version):
if app.builder.format != 'html' or app.builder.name == 'epub':
return
for literal_block_node in doctree.traverse(docutils.nodes.literal_block):
assert 'language' in literal_block_node.attributes
language = literal_block_node.attributes['language'].lower()
if language in ['solidity', 'yul']:
text_nodes = list(literal_block_node.traverse(docutils.nodes.Text))
assert len(text_nodes) == 1
remix_url = remix_code_url(text_nodes[0], language, solidity_version)
url_length = len(remix_url.encode('utf-8'))
if url_length > MAX_SAFE_URL_LENGTH:
logger.warning(
"Remix URL generated from the code snippet exceeds the maximum safe URL length "
" (%d > %d bytes).",
url_length,
MAX_SAFE_URL_LENGTH,
location=(literal_block_node.source, literal_block_node.line),
)
insert_node_before(literal_block_node, build_remix_link_node(remix_url))
def setup(app):
# NOTE: Need to access _raw_config here because setup() runs before app.config is ready.
solidity_version = app.config._raw_config['version'] # pylint: disable=protected-access
app.connect(
'doctree-resolved',
lambda app, doctree, docname: insert_remix_link(app, doctree, solidity_version)
)
return {
'version': solidity_version,
'parallel_read_safe': True,
'parallel_write_safe': True,
}