Source code for robot.libdocpkg.markdownformatter

#  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 textwrap
from typing import TYPE_CHECKING

from robot.model import Tags
from robot.running import ArgInfo, ArgumentSpec
from robot.utils import file_writer

if TYPE_CHECKING:
    from .model import KeywordDoc, LibraryDoc


[docs] class LibdocMarkdownWriter: """Writes the full library/resource documentation as a single Markdown file. Formatting is the same that is used when viewing documentation on console. Actual documentation is got directly from the library/resource, so the result is proper Markdown only if the library uses Markdown as its documentation format. """
[docs] def write(self, libdoc, output): with file_writer(output) as outfile: outfile.write(MarkdownFormatter(libdoc).format())
[docs] class MarkdownFormatter: def __init__(self, libdoc: "LibraryDoc"): self.libdoc = libdoc
[docs] def format(self) -> str: md = self.format_introduction() md += self.format_importing() md += self.format_keywords() return md
[docs] def format_introduction(self) -> str: md = f"# {self.libdoc.name}\n\n" if self.libdoc.version: md += f"* Version: {self.libdoc.version}\n" if self.libdoc.type == "LIBRARY": md += f"* Scope: {self.libdoc.scope}\n" if self.libdoc.version or self.libdoc.type == "LIBRARY": md += "\n" if self.libdoc.doc: md += "## Introduction\n\n" md += self.libdoc.doc + "\n\n" return md
[docs] def format_importing(self) -> str: if not self.libdoc.inits: return "" md = "## Importing\n\n" formatter = KeywordFormatter(init=True) for init in self.libdoc.inits: md += formatter.format(init) return md
[docs] def format_keywords(self, header: bool = True) -> str: if not self.libdoc.keywords: return "" md = "## Keywords\n\n" if header else "" formatter = KeywordFormatter() for kw in self.libdoc.keywords: md += formatter.format(kw) return md
[docs] class KeywordFormatter: def __init__(self, init=False): self.init = init
[docs] def format(self, keyword: "KeywordDoc") -> str: md = f"### {keyword.name}\n\n" if not self.init else "" md += self._format_args(keyword.args) md += self._format_returns(keyword.args) md += self._format_raises(keyword.args) md += self._format_tags(keyword.tags) md += self._format_doc(keyword.doc) return md
def _format_args(self, args: ArgumentSpec) -> str: if not args: return "" md = "#### Arguments\n\n" for arg in args: if not arg.is_marker: md += self._format_arg_name(arg) md += self._format_arg_info(arg) md += self._format_arg_doc(arg) md += "\n" return md + "\n" def _format_arg_name(self, arg: ArgInfo) -> str: if arg.kind == ArgInfo.VAR_POSITIONAL: marker = "*" elif arg.kind == ArgInfo.VAR_NAMED: marker = "**" else: marker = "" return f"* `{marker}{arg.name}`" def _format_arg_info(self, arg: ArgInfo) -> str: info = [] if arg.type: info.append(f"type: `{arg.type}`") if arg.default_repr is not None: info.append(f"default: `{arg.default_repr}`") if arg.kind == ArgInfo.POSITIONAL_ONLY: info.append("positional-only") if arg.kind == ArgInfo.NAMED_ONLY: info.append("named-only") if not info: return "" return f" ({', '.join(info)})" def _format_arg_doc(self, arg: ArgInfo) -> str: if not arg.doc: return "" doc = textwrap.indent(arg.doc, " ") return f" -\n{doc}" def _format_returns(self, args: ArgumentSpec) -> str: if not (args.return_type or args.return_doc): return "" md = "#### Returns\n\n" md += f"* `{args.return_type}`" doc = textwrap.indent(args.return_doc, " ") if doc: md += f" -\n{doc}" return md + "\n\n" def _format_raises(self, args: ArgumentSpec) -> str: if not args.raises: return "" md = "#### Raises\n\n" for name, doc in args.raises.items(): doc = textwrap.indent(doc, " ") md += f"* `{name}` -\n{doc}\n" return md + "\n" def _format_tags(self, tags: Tags) -> str: if not tags: return "" md = "#### Tags\n\n" for tag in tags: md += f"* `{tag}`\n" return md + "\n" def _format_doc(self, doc: str) -> str: if not doc: return "" md = "#### Documentation\n\n" return md + doc + "\n\n"