#!/usr/bin/env python#  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."""Module implementing the command line entry point for the Libdoc tool.This module can be executed from the command line using the followingapproaches::    python -m robot.libdoc    python path/to/robot/libdoc.pyThis module also exposes the following public API:- :func:`libdoc_cli` function for simple command line tools.- :func:`libdoc` function as a high level programmatic API.- :func:`~robot.libdocpkg.builder.LibraryDocumentation` as the API to generate  :class:`~robot.libdocpkg.model.LibraryDoc` instances.Libdoc itself is implemented in the :mod:`~robot.libdocpkg` package."""importsysfrompathlibimportPathif__name__=="__main__"and"robot"notinsys.modules:frompythonpathsetterimportset_pythonpathset_pythonpath()fromrobot.errorsimportDataErrorfromrobot.libdocpkgimport(ConsoleViewer,format_languages,LANGUAGES,LibraryDocumentation)fromrobot.utilsimportApplication,seq2strUSAGE=f"""Libdoc -- Robot Framework library documentation generatorVersion:  <VERSION>Usage:  libdoc [options] library_or_resource output_file   or:  libdoc [options] library_or_resource list|show|version [names]Libdoc can generate documentation for Robot Framework libraries and resourcefiles. It can generate HTML documentation for humans as well as machinereadable spec files in XML and JSON formats. Libdoc also has few specialcommands to show library or resource information on the console.Libdoc supports all library and resource types and also earlier generated XMLand JSON specs can be used as input. If a library needs arguments, they must begiven as part of the library name and separated by two colons, for example,like `LibraryName::arg1::arg2`.The easiest way to run Libdoc is using the `libdoc` command created as part ofthe normal installation. Alternatively it is possible to execute the`robot.libdoc` module directly like `python -m robot.libdoc`, where `python`can be replaced with any supported Python interpreter. Yet another alternativeis running the module as a script like `python path/to/robot/libdoc.py`.Options======= -f --format HTML|XML|JSON|LIBSPEC                          Specifies whether to generate an HTML output for                          humans or a machine readable spec file in XML or JSON                          format. The LIBSPEC format means XML spec with                          documentations converted to HTML. The default format                          is got from the output file extension. -s --specdocformat RAW|HTML                          Specifies the documentation format used with XML and                          JSON spec files. RAW means preserving the original                          documentation format and HTML means converting                          documentation to HTML. The default is RAW with XML                          spec files and HTML with JSON specs and when using                          the special LIBSPEC format. -F --docformat ROBOT|HTML|TEXT|REST                          Specifies the source documentation format. Possible                          values are Robot Framework's documentation format,                          HTML, plain text, and reStructuredText. The default                          value can be specified in library source code and                          the initial default value is ROBOT.    --theme DARK|LIGHT|NONE                          Use dark or light HTML theme. If this option is not                          used, or the value is NONE, the theme is selected                          based on the browser color scheme. New in RF 6.0.    --language lang       Set the default language used in HTML outputs.                          `lang` must be one of the built-in language codes:{format_languages()}                          New in RF 7.2. -n --name name           Sets the name of the documented library or resource. -v --version version     Sets the version of the documented library or                          resource.    --quiet               Do not print the path of the generated output file                          to the console. -P --pythonpath path *   Additional locations where to search for libraries                          and resources. -h -? --help             Print this help.Creating documentation======================When creating documentation in HTML, XML or JSON format, the output file mustbe specified as the second argument after the library or resource name or path.Output format is got automatically from the output file extension. In additionto `*.html`, `*.xml` and `*.json` extensions, it is possible to use the special`*.libspec` extensions which means XML spec with actual library and keyworddocumentation converted to HTML. The format can also be set explicitly usingthe `--format` option.Examples:  libdoc src/MyLibrary.py doc/MyLibrary.html  libdoc doc/MyLibrary.json doc/MyLibrary.html  libdoc --name MyLibrary Remote::10.0.0.42:8270 MyLibrary.xml  libdoc MyLibrary MyLibrary.libspecViewing information on console==============================Libdoc has three special commands to show information on the console. Thesecommands are used instead of the name of the output file, and they can alsotake additional arguments.list:    List names of the keywords the library/resource contains. Can be         limited to show only certain keywords by passing optional patterns as         arguments. Keyword is listed if its name contains any given pattern.show:    Show library/resource documentation. Can be limited to show only         certain keywords by passing names as arguments. Keyword is shown if         its name matches any given name. Special argument `intro` will show         the library introduction and importing sections.version: Show library versionOptional patterns given to `list` and `show` are case and space insensitive.Both also accept `*` and `?` as wildcards.Examples:  libdoc Dialogs list  libdoc SeleniumLibrary list browser  libdoc Remote::10.0.0.42:8270 show  libdoc Dialogs show PauseExecution execute*  libdoc SeleniumLibrary show intro  libdoc SeleniumLibrary versionAlternative execution=====================Libdoc works with all interpreters supported by Robot Framework. In the examples above Libdoc is executed as aninstalled module, but it can also be executed as a script like`python path/robot/libdoc.py`.For more information about Libdoc and other built-in tools, seehttp://robotframework.org/robotframework/#built-in-tools."""
[docs]classLibDoc(Application):def__init__(self):super().__init__(USAGE,arg_limits=(2,),auto_version=False)
[docs]defvalidate(self,options,arguments):ifConsoleViewer.handles(arguments[1]):ConsoleViewer.validate_command(arguments[1],arguments[2:])returnoptions,argumentsiflen(arguments)>2:raiseDataError("Only two arguments allowed when writing output.")returnoptions,arguments
[docs]defmain(self,args,name="",version="",format=None,docformat=None,specdocformat=None,theme=None,language=None,pythonpath=None,quiet=False,):ifpythonpath:sys.path=pythonpath+sys.pathlib_or_res,output=args[:2]docformat=self._get_docformat(docformat)libdoc=LibraryDocumentation(lib_or_res,name,version,docformat)ifConsoleViewer.handles(output):ConsoleViewer(libdoc).view(output,*args[2:])returnformat,specdocformat=self._get_format_and_specdocformat(format,specdocformat,output)if(format=="HTML"orspecdocformat=="HTML"or(formatin("JSON","LIBSPEC")andspecdocformat!="RAW")):libdoc.convert_docs_to_html()libdoc.save(output,format,self._validate_theme(theme,format),self._validate_lang(language),)ifnotquiet:self.console(Path(output).absolute())
def_get_docformat(self,docformat):returnself._validate("Doc format",docformat,("ROBOT","TEXT","HTML","REST"),)def_get_format_and_specdocformat(self,format,specdocformat,output):extension=Path(output).suffix[1:]format=self._validate("Format",formatorextension,("HTML","XML","JSON","LIBSPEC"),allow_none=False,)specdocformat=self._validate("Spec doc format",specdocformat,("RAW","HTML"),)ifformat=="HTML"andspecdocformat:raiseDataError("The --specdocformat option is not applicable with HTML outputs.")returnformat,specdocformatdef_validate(self,kind,value,valid,allow_none=True):ifvalue:value=value.upper()elifallow_none:returnNoneifvaluenotinvalid:raiseDataError(f"{kind} must be{seq2str(valid,lastsep=' or ')}, got '{value}'.")returnvaluedef_validate_theme(self,theme,format):theme=self._validate("Theme",theme,("DARK","LIGHT","NONE"))ifnotthemeortheme=="NONE":returnNoneifformat!="HTML":raiseDataError("The --theme option is only applicable with HTML outputs.")returnthemedef_validate_lang(self,lang):returnself._validate("Language",lang,valid=[*LANGUAGES,"NONE"])
[docs]deflibdoc_cli(arguments=None,exit=True):"""Executes Libdoc similarly as from the command line.    :param arguments: Command line options and arguments as a list of strings.        Defaults to ``sys.argv[1:]`` if not given.    :param exit: If ``True``, call ``sys.exit`` automatically.    The :func:`libdoc` function may work better in programmatic usage.    Example::        from robot.libdoc import libdoc_cli        libdoc_cli(['--version', '1.0', 'MyLibrary.py', 'MyLibrary.html'])    """ifargumentsisNone:arguments=sys.argv[1:]LibDoc().execute_cli(arguments,exit=exit)
[docs]deflibdoc(library_or_resource,outfile,name="",version="",format=None,docformat=None,specdocformat=None,quiet=False,):"""Executes Libdoc.    :param library_or_resource: Name or path of the library or resource        file to be documented.    :param outfile: Path to the file where to write outputs.    :param name: Custom name to give to the documented library or resource.    :param version: Version to give to the documented library or resource.    :param format: Specifies whether to generate HTML, XML or JSON output.        If this options is not used, the format is got from the extension of        the output file. Possible values are ``'HTML'``, ``'XML'``, ``'JSON'``        and ``'LIBSPEC'``.    :param docformat: Documentation source format. Possible values are        ``'ROBOT'``, ``'reST'``, ``'HTML'`` and ``'TEXT'``. The default value        can be specified in library source code and the initial default        is ``'ROBOT'``.    :param specdocformat: Specifies whether the keyword documentation in spec        files is converted to HTML regardless of the original documentation        format. Possible values are ``'HTML'`` (convert to HTML) and ``'RAW'``        (use original format). The default depends on the output format.    :param quiet: When true, the path of the generated output file is not        printed the console.    Arguments have same semantics as Libdoc command line options with same names.    Run ``libdoc --help`` or consult the Libdoc section in the Robot Framework    User Guide for more details.    Example::        from robot.libdoc import libdoc        libdoc('MyLibrary.py', 'MyLibrary.html', version='1.0')    """returnLibDoc().execute(library_or_resource,outfile,name=name,version=version,format=format,docformat=docformat,specdocformat=specdocformat,quiet=quiet,)
if__name__=="__main__":libdoc_cli(sys.argv[1:])