<commit_before>Library documentation tool (:prog:`libdoc`)
-------------------------------------------

:prog:`libdoc.py` is a tool for generating keyword documentation for test
libraries and resource files in HTML and XML formats. Documentation can be
created for both test libraries and resource files. It is built-in into Robot
Framework and automatically included in the installation starting from
version 2.7.

Synopsis
~~~~~~~~

::

    libdoc.py [options] library_or_resource

Options
~~~~~~~

  -f, --format <html|xml>  Specifies whether to generate HTML or XML output.
                           If this options is not used, the format is got
                           from the extension of output, if given. Otherwise
                           the default is HTML.
  -o, --output <path>      File to write the generated documentation to. If
                           not given, documentation is written to the standard
                           output.
  -N, --name <newname>     Sets the name of the documented library or resource.
  -V, --version <newversion>  Sets the version of the documented library or
                           resource.
  -a, --argument <value>   Possible argument(s) that the documented library
                           needs for initialization.
  -P, --pythonpath <path>  Additional path(s) to insert into PYTHONPATH.
  -E, --escape <what:with>  Escapes characters which are problematic in console.
                           :opt:`what` is the name of the character to escape
                           and :opt:`with` is the string to escape it with.
                           Available escapes are listed in the :opt:`--help`
                           output.
  -h, --help               Prints this help.

Description
~~~~~~~~~~~

:prog:`libdoc.py` is a tool for generating keyword documentation for test
libraries and resource files in HTML and XML formats. The former format is
suitable for humans and the latter for RIDE_ and other tools.

Documentation can be created for:

- Test libraries implemented with Python__ or Java__ using the normal
  library API
- Test libraries using the `dynamic API`__
- `Resource files`_

Additionally it is possible to use XML documentation created earlier by
`libdoc.py` or other tools as input.

__ `Python libraries`_
__ `Java libraries`_
__ `Dynamic libraries`_

Specifying the library or resource file
'''''''''''''''''''''''''''''''''''''''

It is possible to specify a Python test library by giving either the
path to the source or only the library name. If the library name is
used, it must be in the same format as in the Robot Framework test
data when importing libraries. In this case, the library is searched
from PYTHONPATH (and from CLASSPATH, if on Jython).

A Java test library implemented with a normal library API can be
specified by giving the path to the source code file containing the
library implementation. Additionally, :path:`tools.jar`, which is part
of the Sun JDK distribution, must be found from CLASSPATH when
:prog:`libdoc.py` is executed. When generating documentation for Java
libraries, :prog:`libdoc.py` must be executed using Jython.

Libraries using the dynamic library API are handled in the same way as
Python libraries.

Some libraries require arguments when they are imported and they can
be given using :opt:`--argument` option. It can be used multiple times
to specify multiple arguments. Libraries always get these arguments as
strings. If arguments change what keywords the library provides or
otherwise change its behavior, it might be a good idea to use
:opt:`--name` option to also change the library name accordingly.

Resource files must always be specified using a path. If the path does
not exist, resource files are also searched from all directories in
PYTHONPATH.

Examples
~~~~~~~~

::

   python -m robot.libdoc OperatingSystem
   python -m robot.libdoc --output doc/MyLib.html src/MyLib.py
   python -m robot.libdoc --argument arg1 --argument arg2 LibraryWithArgs.py
   python -m robot.libdoc --name MyLibrary --argument 10.0.0.42:8270 Remote.py
   python -m robot.libdoc test/resource.html
   python -m robot.libdoc --format xml OperatingSystem
   python -m robot.libdoc --format xml --output doc test/resource.html
   jython -m robot.libdoc --output MyJavaLibrary.xml MyJavaLibrary.java

Writing documentation
~~~~~~~~~~~~~~~~~~~~~

`Creating test libraries`_ and `resource files`_ is described in more
details elsewhere in this guide.

Python libraries
''''''''''''''''

The documentation for Python libraries is written simply as doc
strings for the library class and for methods implementing
keywords. The first line of the method documentation is considered as
a short documentation for the keywords (used for example as a tool tip in
links in the generated HTML documentation), and it should thus be as
describing as possible, but not too long.

The simple example below illustrates how to write the documentation,
and for example `standard libraries`_ give more
realistic examples. For more information on Python documentation<commit_msg>userguide: update libdoc after cmd line changes<commit_after>Library documentation tool (:prog:`libdoc`)
-------------------------------------------

:prog:`libdoc.py` is a tool for generating keyword documentation for test
libraries and resource files in HTML and XML formats. Documentation can be
created for both test libraries and resource files. It is built-in into Robot
Framework and automatically included in the installation starting from
version 2.7.

Synopsis
~~~~~~~~

::

    libdoc.py [options] library_or_resource output_file

Options
~~~~~~~

  -f, --format <html|xml>  Specifies whether to generate HTML or XML output.
                           If this options is not used, the format is got
                           from the extension of the output file.
  -N, --name <newname>     Sets the name of the documented library or resource.
  -V, --version <newversion>  Sets the version of the documented library or
                           resource.
  -a, --argument <value>   Possible argument(s) that the documented library
                           needs for initialization.
  -P, --pythonpath <path>  Additional path(s) to insert into PYTHONPATH.
  -E, --escape <what:with>  Escapes characters which are problematic in console.
                           :opt:`what` is the name of the character to escape
                           and :opt:`with` is the string to escape it with.
                           Available escapes are listed in the :opt:`--help`
                           output.
  -h, --help               Prints this help.

Description
~~~~~~~~~~~

:prog:`libdoc.py` is a tool for generating keyword documentation for test
libraries and resource files in HTML and XML formats. The former format is
suitable for humans and the latter for RIDE_ and other tools.

Documentation can be created for:

- Test libraries implemented with Python__ or Java__ using the normal
  library API
- Test libraries using the `dynamic API`__
- `Resource files`_

Additionally it is possible to use XML documentation created earlier by
`libdoc.py` or other tools as input.

__ `Python libraries`_
__ `Java libraries`_
__ `Dynamic libraries`_

Specifying the library or resource file
'''''''''''''''''''''''''''''''''''''''

It is possible to specify a Python test library by giving either the
path to the source or only the library name. If the library name is
used, it must be in the same format as in the Robot Framework test
data when importing libraries. In this case, the library is searched
from PYTHONPATH (and from CLASSPATH, if on Jython).

A Java test library implemented with a normal library API can be
specified by giving the path to the source code file containing the
library implementation. Additionally, :path:`tools.jar`, which is part
of the Sun JDK distribution, must be found from CLASSPATH when
:prog:`libdoc.py` is executed. When generating documentation for Java
libraries, :prog:`libdoc.py` must be executed using Jython.

Libraries using the dynamic library API are handled in the same way as
Python libraries.

Some libraries require arguments when they are imported and they can
be given using :opt:`--argument` option. It can be used multiple times
to specify multiple arguments. Libraries always get these arguments as
strings. If arguments change what keywords the library provides or
otherwise change its behavior, it might be a good idea to use
:opt:`--name` option to also change the library name accordingly.

Resource files must always be specified using a path. If the path does
not exist, resource files are also searched from all directories in
PYTHONPATH.

Examples
~~~~~~~~

::

   python -m robot.libdoc OperatingSystem OperatingSystem.html
   python -m robot.libdoc --argument arg1 --argument arg2 LibraryWithArgs.py spec.xml
   python -m robot.libdoc --name MyLibrary --argument 10.0.0.42:8270 Remote.py Remote.html
   python -m robot.libdoc test/resource.html doc/resource_doc.html
   python -m robot.libdoc --format xml src/MyLib.py output.txt
   jython -m robot.libdoc MyJavaLibrary.java MyJavaLibrary.xml

Writing documentation
~~~~~~~~~~~~~~~~~~~~~

`Creating test libraries`_ and `resource files`_ is described in more
details elsewhere in this guide.

Python libraries
''''''''''''''''

The documentation for Python libraries is written simply as doc
strings for the library class and for methods implementing
keywords. The first line of the method documentation is considered as
a short documentation for the keywords (used for example as a tool tip in
links in the generated HTML documentation), and it should thus be as
describing as possible, but not too long.

The simple example below illustrates how to write the documentation,
and for example `standard libraries`_ give more
realistic examples. For more information on Python documentation
{'fraction_non_alphanumeric': 0.07911200807265388, 'fraction_numerical': 0.0028254288597376388, 'mean_word_length': 3.215652913653764, 'pattern_counts': {'":': 0, '<': 16, '<?xml version=': 0, '>': 16, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 8}, 'pii_count': 2, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2880028', 'n_tokens_mistral': 2464, 'n_tokens_neox': 2392, 'n_words': 1293}