def _load_keywords(self, collection_id, path=None, libdoc=None):
"""Load a collection of keywords
One of path or libdoc needs to be passed in...
"""
if libdoc is None and path is None:
raise (
Exception("You must provide either a path or libdoc argument"))
if libdoc is None:
libdoc = LibraryDocumentation(path)
if len(libdoc.keywords) > 0:
for keyword in libdoc.keywords:
self._add_keyword(collection_id, keyword.name, keyword.doc,
keyword.args)
def convert_path(self, path_in, dir_out, format_in, format_out, root=None):
root = root if root is not None else Path.cwd()
# Override default docstring format
if path_in in self.config.get("override_docstring", {}):
self.logger.debug(f"Overriding docstring format for '{path_in}'")
format_in = self.config["override_docstring"][path_in]
# Override default output format
if path_in in self.config.get("override_format", {}):
self.logger.debug(f"Overriding output format for '{path_in}'")
format_out = self.config["override_format"][path_in]
converter = CONVERTERS[format_out]
path_rel = path_in.with_suffix(converter.EXTENSION).relative_to(root)
if self.config.get("collapse", False):
path_rel = Path("_".join(part.lower() for part in path_rel.parts))
path_out = Path(dir_out) / path_rel
path_out.parent.mkdir(parents=True, exist_ok=True)
self.logger.debug("Converting '%s' to '%s'", path_in, path_out)
libdoc = LibraryDocumentation(str(path_in),
doc_format=format_in.upper())
# Override name with user-given value
if self.config.get("title"):
libdoc.name = self.config["title"]
# Create module path for library, e.g. RPA.Excel.Files
elif path_rel.parent != Path("."):
libdoc.name = "{namespace}.{name}".format(
namespace=str(path_rel.parent).replace(os.sep, "."),
name=libdoc.name,
)
# Convert library scope to RPA format
if self.config.get("rpa", False):
scope = normalize(unic(libdoc.scope), ignore="_")
libdoc.scope = {
"testcase": "Task",
"testsuite": "Suite",
"global": "Global",
}.get(scope, "")
converter().convert(libdoc, path_out)
def run(self):
failed = []
for library in self._options.libraries:
try:
xml_doc = StringIO()
# LibraryDocumentation().save() calls close() for the underlying
# file but closing StringIO object discards its data.
# This is why close() is overridden below.
xml_doc.original_close = xml_doc.close
try:
try:
if library.endswith('.xml'):
with open(library) as xml_file:
xml_doc.write(xml_file.read())
else:
xml_doc.close = lambda: None
LibraryDocumentation(library).save(xml_doc, 'xml')
except DataError as e:
message = "Library not found" if 'ImportError' in e.message else e.message
failed.append(library)
sys.stderr.write(
"Skipping '%s' due to an error: %s.\n" %
(library, message))
continue
xml_doc.name = library
self._uploader.upload_file(xml_doc, self._options.lib_name,
self._options.lib_version)
sys.stdout.write("Updated documentation for '%s'.\n" %
library)
finally:
xml_doc.original_close()
except DataError as e:
failed.append(library)
sys.stderr.write('%s: Remote error: %s\n' %
(os.path.basename(__file__), e.message))
if failed:
sys.stderr.write('\nERROR: Uploading %d file(s) failed:\n' %
len(failed))
for name in failed:
sys.stderr.write('* %s\n' % name)
exit(1)
def generate_documentation(file):
"""Generate robot framework html documentation for file
Args:
file (filepath): filepath to robot resource/library
Returns:
string: html documentation for the file
"""
# Using tempfile is required because robot libdoc wants path-like-object
fd, fname = mkstemp()
try:
LibraryDocumentation(file).save(fname, "html")
except Exception as e:
logging.warning("Was not able to generate documentation for {}. Got error {}".format(file, e))
raise LibdocError(str(e))
with open(fname, "r") as f:
content = f.read()
os.close(fd)
os.remove(fname)
return content
def main(self,
args,
name='',
version='',
format=None,
docformat=None,
specdocformat=None,
quiet=False):
lib_or_res, output = args[:2]
docformat = self._get_docformat(docformat)
libdoc = LibraryDocumentation(lib_or_res, name, version, docformat)
if ConsoleViewer.handles(output):
ConsoleViewer(libdoc).view(output, *args[2:])
return
format, specdocformat \
= self._get_format_and_specdocformat(format, specdocformat, output)
if (format == 'HTML' or specdocformat == 'HTML'
or format in ('JSON', 'LIBSPEC') and specdocformat != 'RAW'):
libdoc.convert_docs_to_html()
libdoc.save(output, format)
if not quiet:
self.console(os.path.abspath(output))
def _load_libdoc(self, name, source=None, use_cache=True):
""" Try to load a libdoc, either by name, or named source. Tries to use
the cache.
"""
strategies = [name]
if source is not None and source.endswith(".robot"):
try:
strategies += [find_file(source)]
except Exception:
pass
for strategy in strategies:
if use_cache and strategy in self._doc_cache:
return self._doc_cache[strategy]
try:
libdoc = LibraryDocumentation(strategy)
self._doc_cache[strategy] = self._doc_cache[name] = libdoc
return libdoc
except Exception as err:
pass
self.log.debug("Could not load libdoc for %s: %s", strategy, err)
def test_extract_doc_from_libdoc_inits_should_return_doc_from_init(self):
file = str(self.fixture_path / "LibWithInit")
libdoc = LibraryDocumentation(file)
init_doc = self.rfhub_extractor._extract_doc_from_libdoc_inits(
libdoc.inits)
self.assertEqual(init_doc, EXPECTED_INIT_DOC)
def test_extract_doc_from_libdoc_inits_should_return_empty_string(self):
file = str(self.fixture_path / "SingleClassLib" / "SingleClassLib.py")
libdoc = LibraryDocumentation(file)
init_doc = self.rfhub_extractor._extract_doc_from_libdoc_inits(
libdoc.inits)
self.assertEqual(init_doc, "")
def test_serialise_libdoc_should_return_collection(self):
file = self.fixture_path / "test_libdoc_file.xml"
libdoc_1 = LibraryDocumentation(file)
serialised_libdoc = self.rfhub_extractor._serialise_libdoc(
libdoc_1, str(file))
self.assertEqual(serialised_libdoc, EXPECTED_COLLECTION_2)
def test_serialise_keywords_should_return_keywords(self):
file = self.fixture_path / "test_resource.resource"
libdoc_2 = LibraryDocumentation(file)
serialised_keywords = self.rfhub_extractor._serialise_keywords(
libdoc_2)
self.assertEqual(serialised_keywords, EXPECTED_KEYWORDS)
def is_module_library(path):
return (path / "__init__.py").is_file() and bool(
LibraryDocumentation(str(path)).keywords
)
def _is_library_with_init(path: Path) -> bool:
return (path / "__init__.py").is_file() and len(
LibraryDocumentation(str(path)).keywords) > 0
def get_documentation(file):
try:
return LibraryDocumentation(file)
except Exception as e:
logging.warning("Was not able to generate documentation for {}. Got error {}".format(file, e))
raise LibdocError(str(e))
def run_libdoc_and_validate_json(filename):
library = join(DATADIR, filename)
json_spec = LibraryDocumentation(library).to_json()
with open(join(CURDIR, '../../doc/schema/libdoc.json')) as f:
schema = json.load(f)
validate(instance=json.loads(json_spec), schema=schema)
def libdoc(library, out=None, name=None, version=None, format=None,
docformat=None, **options):
"""Alternative to :func:`robot.libdoc` with the following extra features:
- `out` can be a file path (with implicit format from extension)
or a stream object (which won't be flushed or closed).
In both cases, the number of written characters will be returned.
- If `out` is ``None``, the document text will be returned.
- For 'html' format, some extra post-processing `options` are supported:
- If ``standalone=False``, the ``<html>``, ``<head>``, ``<meta>``,
and ``<body>`` tags will be stripped to make the document embeddable
in existing HTML documents without the use of ``<iframe>``s
- ``heading=`` can be set to an alternative main heading text
(which defaults to the library name)
or to ``False`` to completely remove the heading element.
"""
outpath = isstring(out) and Path(out)
if outpath and not format:
# get implicit format from file extension
_, ext = Path(out).splitext()
format = ext[1:] # remove leading '.'
if not format:
raise ValueError("Missing format for robottools.libdoc()")
if format not in FORMATS:
raise ValueError(
"Invalid robottools.libdoc() format: %s" % repr(format))
if format != 'html' and options:
raise RuntimeError(
"robottools.libdoc() doesn't support extra options for %s format."
% repr(format))
if out is not None:
class Stream(object):
"""Simple out stream wrapper for counting written characters
and preventing stream closing.
"""
count = 0
# look like a text stream
encoding = 'utf8'
def write(self, text):
self.count += len(text)
out.write(text)
def close(self):
pass
else: # memory stream for returning text
class Stream(StringIO):
"""StringIO with close prevention.
"""
def close(self):
pass
stream = Stream()
if outpath:
# need `str` stream in PY2 and PY3
out = open(outpath, 'w')
doc = LibraryDocumentation(library, name, version, docformat)
LibdocWriter(format).write(
doc, stream if format != 'html' else HTML(stream, **options))
if out is not None:
if outpath:
out.close()
return stream.count
# else return the text from StringIO
stream.seek(0)
text = stream.read()
StringIO.close(stream) # close was overridden
return text
def get_keywords(file):
doc = LibraryDocumentation(file)
return doc.keywords
def __init__(self, path):
self.datafile = ResourceFile(path).populate()
self.doc = LibraryDocumentation(path)
def run_libdoc_and_validate_json(filename):
library = path.join(testdata_dir, filename)
libdoc = LibraryDocumentation(library)
libspec = libdoc.to_dictionary()
validate_dict_to_json_schema(libspec)
def _looks_like_library_with_init(self, path):
return os.path.isfile(os.path.join(path, '__init__.py')) and \
len(LibraryDocumentation(path).keywords) > 0
