# Copyright 2008-2015 Nokia Networks
# Copyright 2016- Robot Framework Foundation
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
import re
from typing import Callable, Dict, Iterable, TYPE_CHECKING
from urllib.parse import quote
from robot.api.deco import DocFormat
from robot.errors import DataError
from robot.utils import (
attribute_escape, html_escape, html_format, NormalizedDict, validate_literal
)
from robot.utils.htmlformatters import HeaderFormatter
from robot.utils.markdown import AdmonitionExtension, LinkifyExtension, Markdown
if TYPE_CHECKING:
from .model import KeywordDoc
try:
from docutils import __version_info__ as docutils_version
from docutils.core import publish_parts
except ImportError:
def publish_parts(*args, **kwargs):
raise DataError(
"The 'docutils' module is required to convert reStructuredText "
"documentation to HTML."
)
Targets = Dict[str, "tuple[str, str]"]
TargetTriplet = Iterable["tuple[str, str, str]"]
[docs]
def fragment(value):
# Emulates encodeURIComponent JavaScript function
return "#" + quote(value.encode("UTF-8"), safe="-_.!~*'()")
[docs]
class DocToHtml:
def __init__(self, doc_format: DocFormat, targets: "Targets | None" = None):
self.formatter = self._get_formatter(doc_format)
self.targets = NormalizedDict(targets)
self._md = None
def _get_formatter(self, doc_format: DocFormat) -> Callable[[str], str]:
try:
doc_format = validate_literal(doc_format, DocFormat, "documentation format")
except ValueError as err:
raise DataError(str(err))
return {
"ROBOT": self._format_robot,
"TEXT": self._format_text,
"HTML": self._format_html,
"REST": self._format_rest,
"MARKDOWN": self._format_markdown,
}[doc_format]
def __call__(self, doc: str) -> str:
return self.formatter(doc)
[docs]
def reset(self):
if self._md is not None:
self._md.reset()
self._md.references = self.targets.copy()
def _format_robot(self, doc: str) -> str:
toc = self._get_toc(doc) if "%TOC%" in doc else None
doc = html_format(doc)
if toc:
doc = doc.replace("<p>%TOC%</p>", toc)
doc = re.sub(r"<h([234])>(.+?)</h\1>", r'<h\1 id="\2">\2</h\1>', doc)
return self._handle_backtick_links(doc)
def _get_toc(self, doc):
entries = re.findall(r"^\s*(={1,2})\s+(.+?)\s+\1\s*$", doc, flags=re.MULTILINE)
items = []
for level, header in entries:
if level == "=":
items.append((header, []))
elif items:
items[-1][1].append(header)
lines = []
for header, nested in items:
lines.extend(self._toc_item(header, nested))
return "\n".join(self._toc_block(lines))
def _toc_item(self, header, nested=()):
link = f'<a href="{fragment(header)}">{header}</a>'
if not nested:
return [f"<li>{link}</li>"]
# Nested list must be inside the item, not a sibling of it.
sub_items = [line for sub in nested for line in self._toc_item(sub)]
return [f"<li>{link}", *self._toc_block(sub_items), "</li>"]
def _toc_block(self, items):
return ["<ul>", *items, "</ul>"]
def _format_text(self, doc: str) -> str:
doc = self._handle_backtick_links(html_escape(doc))
return f'<p style="white-space: pre-wrap">{doc}</p>'
def _format_html(self, doc: str) -> str:
return self._handle_backtick_links(doc)
def _format_rest(self, doc: str) -> str:
writer = "writer" if docutils_version >= (0, 22) else "writer_name"
parts = publish_parts(
doc,
settings_overrides={"syntax_highlight": "short"},
**{writer: "html"},
)
return self._handle_backtick_links(parts["html_body"])
def _format_markdown(self, doc: str) -> str:
if self._md is None:
self._md = Markdown(
extensions=[
"codehilite",
"fenced_code",
"sane_lists",
"tables",
"toc",
AdmonitionExtension(),
LinkifyExtension(),
],
extension_configs={
"toc": {"baselevel": 2, "toc_depth": 3, "marker": "%TOC%"},
"codehilite": {
"css_class": "code",
"linenums": False,
"guess_lang": False,
},
},
output_format="html",
)
self._md.references = self.targets.copy()
return self._md.convert(doc)
def _handle_backtick_links(self, doc: str) -> str:
return re.sub("`(.+?)`", self._handle_names, doc)
def _handle_names(self, match: "re.Match[str]") -> str:
name = match.group(1)
if name in self.targets:
target, title = self.targets[name]
return f'<a href="{target}" title="{title}" class="name">{name}</a>'
return f'<span class="name">{name}</span>'
[docs]
class HtmlToText:
html_tags = {
"b": "*",
"i": "_",
"strong": "*",
"em": "_",
"code": "``",
"div.*?": "",
}
html_chars = {
"<br */?>": "\n",
"&": "&",
"<": "<",
">": ">",
""": '"',
"'": "'",
}
[docs]
def get_short_doc_from_html(self, doc):
match = re.search(r"<p.*?>(.*?)</?p>", doc, re.DOTALL)
if match:
doc = match.group(1)
return self.html_to_plain_text(doc)
[docs]
def html_to_plain_text(self, doc):
for tag, repl in self.html_tags.items():
doc = re.sub(
rf"<{tag}>(.*?)</{tag}>",
rf"{repl}\1{repl}",
doc,
flags=re.DOTALL,
)
for html, text in self.html_chars.items():
doc = re.sub(html, text, doc)
return doc