def main(self, args, name='', version='', format=None):
lib_or_res, output = args[:2]
libdoc = LibraryDocumentation(lib_or_res, name, version)
if ConsoleViewer.handles(output):
ConsoleViewer(libdoc).view(output, *args[2:])
else:
libdoc.save(output, self._get_format(format, output))
self.console(os.path.abspath(output))
def _imain(self, args, name='', version='', format=None, docformat=None, sourcelines=False):
lib_or_res, output = args[:2]
libdoc = LibraryDocumentation(lib_or_res, name, version,
self._get_doc_format(docformat), sourcelines)
if ConsoleViewer.handles(output):
ConsoleViewer(libdoc, sourcelines).view(output, *args[2:])
else:
libdoc.save(output, self._get_output_format(format, output))
self.console(os.path.abspath(output))
def add_file(self, path):
"""Add a resource file or library file to the database"""
libdoc = LibraryDocumentation(path)
if len(libdoc.keywords) > 0:
if libdoc.doc.startswith("Documentation for resource file"):
# bah! The file doesn't have an file-level documentation
# and libdoc substitutes some placeholder text.
libdoc.doc = ""
collection_id = self.add_collection(path, libdoc.name, libdoc.type,
libdoc.doc, libdoc.version,
libdoc.scope, libdoc.named_args,
libdoc.doc_format)
self._load_keywords(collection_id, libdoc=libdoc)
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 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_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_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 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 is_module_library(path):
return (path / "__init__.py").is_file() and bool(
LibraryDocumentation(str(path)).keywords)
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 _is_library_with_init(path: Path) -> bool:
return (path / "__init__.py").is_file() and len(
LibraryDocumentation(str(path)).keywords) > 0
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
def __init__(self, path):
self.datafile = ResourceFile(path).populate()
self.doc = LibraryDocumentation(path)
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 get_keywords(file):
doc = LibraryDocumentation(file)
return doc.keywords
