8 new revisions:
Revision: 92f4159c8ace
Author: Pekka Klärck
Date: Mon Feb 20 12:33:03 2012
Log: libdoc tests: better error message when running fails
http://code.google.com/p/robotframework/source/detail?r=92f4159c8ace
Revision: 796e678ce289
Author: Pekka Klärck
Date: Mon Feb 20 12:44:55 2012
Log: doc tweak
http://code.google.com/p/robotframework/source/detail?r=796e678ce289
Revision: 0f6d97ce5f77
Author: Pekka Klärck
Date: Mon Feb 20 12:45:45 2012
Log: libdoc: doc tweaks
http://code.google.com/p/robotframework/source/detail?r=0f6d97ce5f77
Revision: 5cee542442c7
Author: Pekka Klärck
Date: Mon Feb 20 12:54:34 2012
Log: libdoc: Passing possible arguments to libs with --argument option
was ...
http://code.google.com/p/robotframework/source/detail?r=5cee542442c7
Revision: c89923d37afc
Author: Pekka Klärck
Date: Mon Feb 20 13:49:20 2012
Log: UG: new target when discussing libdoc
http://code.google.com/p/robotframework/source/detail?r=c89923d37afc
Revision: 96d58fa899a3
Author: Pekka Klärck
Date: Mon Feb 20 13:49:57 2012
Log: UG: explicit link target for tidy
http://code.google.com/p/robotframework/source/detail?r=96d58fa899a3
Revision: bad1e50ef35d
Author: Pekka Klärck
Date: Mon Feb 20 14:11:34 2012
Log: UG/Tidy: Reorganized
http://code.google.com/p/robotframework/source/detail?r=bad1e50ef35d
Revision: 306199db9384
Author: Pekka Klärck
Date: Mon Feb 20 14:17:53 2012
Log: UG/Libdoc: Clean-up, enhancements, and re-organization....
http://code.google.com/p/robotframework/source/detail?r=306199db9384
==============================================================================
Revision: 92f4159c8ace
Author: Pekka Klärck
Date: Mon Feb 20 12:33:03 2012
Log: libdoc tests: better error message when running fails
http://code.google.com/p/robotframework/source/detail?r=92f4159c8ace
Modified:
/atest/robot/libdoc/libdoc_resource.txt
=======================================
--- /atest/robot/libdoc/libdoc_resource.txt Mon Feb 20 06:38:55 2012
+++ /atest/robot/libdoc/libdoc_resource.txt Mon Feb 20 12:33:03 2012
@@ -17,7 +17,9 @@
Run Libdoc And Parse Output
[Arguments] ${arguments}
- Run Libdoc ${arguments} ${OUTXML}
+ Remove File ${OUTXML}
+ ${output}= Run Libdoc ${arguments} ${OUTXML}
+ Should Not Contain ${output} --help Execution
failed:\n\n${output} no values
Log File ${OUTXML}
${LIBDOC}= Parse Xml ${OUTXML}
Set Suite Variable ${LIBDOC}
==============================================================================
Revision: 796e678ce289
Author: Pekka Klärck
Date: Mon Feb 20 12:44:55 2012
Log: doc tweak
http://code.google.com/p/robotframework/source/detail?r=796e678ce289
Modified:
/src/robot/tidy.py
=======================================
--- /src/robot/tidy.py Wed Feb 15 02:14:03 2012
+++ /src/robot/tidy.py Mon Feb 20 12:44:55 2012
@@ -23,7 +23,7 @@
or: python -m robot.tidy --inplace [options] inputfile [more input
files]
or: python -m robot.tidy --recursive [options] directory
-This tool can be used to clean up and change format of Robot Framework test
+Tidy tool can be used to clean up and change format of Robot Framework test
data files. By default, the output is written to the standard output
stream,
but it can be redirected to a file. Alternatively, files can be modified
in-place using --inplace or --recursive options.
==============================================================================
Revision: 0f6d97ce5f77
Author: Pekka Klärck
Date: Mon Feb 20 12:45:45 2012
Log: libdoc: doc tweaks
http://code.google.com/p/robotframework/source/detail?r=0f6d97ce5f77
Modified:
/src/robot/libdoc.py
=======================================
--- /src/robot/libdoc.py Mon Feb 20 00:26:57 2012
+++ /src/robot/libdoc.py Mon Feb 20 12:45:45 2012
@@ -18,14 +18,14 @@
Version: <VERSION>
-Usage: libdoc.py [options] library_or_resource output_file
-
-This tool can generate keyword documentation in HTML and XML formats. The
-former is suitable for humans and the latter for RIDE and other tools.
+Usage: python -m robot.libdoc [options] library_or_resource output_file
+
+Libdoc tool can generate keyword documentation in HTML and XML formats.
+The former is suitable for humans and the latter for RIDE and other tools.
Documentation can be generated for both test libraries and resource files.
-All library and resource file types are supported, and also documentation
-generated earlier in XML format can be used as input.
+All library and resource file types are supported, and also earlier
generated
+XML documentation can be used as input.
Options
=======
@@ -36,9 +36,8 @@
-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.
+ -P --pythonpath path * Additional locations where to search for
libraries
+ and resources.
-E --escape what:with * Escapes characters which are problematic in
console.
'what' is the name of the character to escape and
'with' is the string to escape it with.
@@ -50,18 +49,17 @@
python -m robot.libdoc src/MyLib.py doc/MyLib.html
python -m robot.libdoc BuiltIn spec.xml
- jython -m robot.libdoc MyJavaLibrary.java MyJavaLibrary.html
- python -m robot.libdoc --format xml test/resource.html myoutfile
+ jython -m robot.libdoc --version 1.0 MyJavaLibrary.java
MyJavaLibrary.html
Alternative execution
=====================
-Libdoc works with all interpretes supported by Robot Framework (Python,
+Libdoc works with all interpreters supported by Robot Framework (Python,
Jython and IronPython). In the examples above libdoc is executed as an
installed module, but it can also be executed as a script like
`python path/robot/libdoc.py`.
-For more information see the Robot Framework user guide at
+For more information see libdoc section in Robot Framework User Guide at
http://code.google.com/p/robotframework/wiki/UserGuide
"""
==============================================================================
Revision: 5cee542442c7
Author: Pekka Klärck
Date: Mon Feb 20 12:54:34 2012
Log: libdoc: Passing possible arguments to libs with --argument option
was very confusing and only a small minority of libs needed them. We
decided to change the logic so that args must be added to the library name
like in 'Lib::a1::a2' when needed.
http://code.google.com/p/robotframework/source/detail?r=5cee542442c7
Modified:
/atest/robot/libdoc/dynamic_library_with_args.txt
/src/robot/libdoc.py
/src/robot/libdocpkg/__init__.py
/src/robot/libdocpkg/javabuilder.py
/src/robot/libdocpkg/robotbuilder.py
/src/robot/libdocpkg/specbuilder.py
=======================================
--- /atest/robot/libdoc/dynamic_library_with_args.txt Tue Feb 14 03:59:52
2012
+++ /atest/robot/libdoc/dynamic_library_with_args.txt Mon Feb 20 12:54:34
2012
@@ -1,5 +1,5 @@
*** Settings ***
-Suite Setup Run Libdoc And Parse Output --argument required
${TESTDATADIR}/DynamicLibrary.py
+Suite Setup Run Libdoc And Parse Output
${TESTDATADIR}/DynamicLibrary.py::required
Force Tags regression pybot jybot
Resource libdoc_resource.txt
=======================================
--- /src/robot/libdoc.py Mon Feb 20 12:45:45 2012
+++ /src/robot/libdoc.py Mon Feb 20 12:54:34 2012
@@ -25,7 +25,9 @@
Documentation can be generated for both test libraries and resource files.
All library and resource file types are supported, and also earlier
generated
-XML documentation can be used as input.
+XML documentation can be used as input. If a library needs arguments, they
+must be given as part of the library name and separated by two colons, for
+example, like `LibraryName::arg1::arg2`.
Options
=======
@@ -48,8 +50,8 @@
========
python -m robot.libdoc src/MyLib.py doc/MyLib.html
- python -m robot.libdoc BuiltIn spec.xml
- jython -m robot.libdoc --version 1.0 MyJavaLibrary.java
MyJavaLibrary.html
+ jython -m robot.libdoc MyJavaLibrary.java MyJavaLibrary.html
+ python -m robot.libdoc --name MyLib Remote::10.0.0.42:8270 MyLib.xml
Alternative execution
=====================
@@ -84,9 +86,9 @@
raise DataError('Only two arguments allowed when writing
output.')
return options, arguments
- def main(self, args, argument=None, name='', version='', format=None):
+ def main(self, args, name='', version='', format=None):
lib_or_res, output = args[:2]
- libdoc = LibraryDocumentation(lib_or_res, argument, name, version)
+ libdoc = LibraryDocumentation(lib_or_res, name, version)
if ConsoleViewer.handles(output):
ConsoleViewer(libdoc).view(output, *args[2:])
else:
@@ -110,14 +112,14 @@
"""
LibDoc().execute_cli(args)
-def libdoc(library_or_resource, output, arguments=None, name='',
version='',
- format=None):
+
+def libdoc(library_or_resource, output, name='', version='', format=None):
"""Executes libdoc.
Arguments are same as command line options to libdoc.py.
Example:
- libdoc('MyLibrary.py', 'MyLibrary.html', arguments=['1st', '2nd'])
+ libdoc('MyLibrary.py', 'MyLibrary.html', version='1.0')
"""
LibDoc().execute(library_or_resource, output, argument=arguments,
name=name, version=version, format=format)
=======================================
--- /src/robot/libdocpkg/__init__.py Mon Feb 20 00:26:57 2012
+++ /src/robot/libdocpkg/__init__.py Mon Feb 20 12:54:34 2012
@@ -16,10 +16,9 @@
from .consoleviewer import ConsoleViewer
-def LibraryDocumentation(library_or_resource, arguments=None, name=None,
- version=None):
+def LibraryDocumentation(library_or_resource, name=None, version=None):
builder = DocumentationBuilder(library_or_resource)
- libdoc = builder.build(library_or_resource, arguments)
+ libdoc = builder.build(library_or_resource)
if name:
libdoc.name = name
if version:
=======================================
--- /src/robot/libdocpkg/javabuilder.py Wed Feb 15 02:29:33 2012
+++ /src/robot/libdocpkg/javabuilder.py Mon Feb 20 12:54:34 2012
@@ -20,7 +20,7 @@
class JavaDocBuilder(object):
- def build(self, path, arguments=None):
+ def build(self, path):
doc = ClassDoc(path)
libdoc = LibraryDoc(name=doc.qualifiedName(),
doc=self._get_doc(doc),
=======================================
--- /src/robot/libdocpkg/robotbuilder.py Wed Feb 15 07:43:46 2012
+++ /src/robot/libdocpkg/robotbuilder.py Mon Feb 20 12:54:34 2012
@@ -24,9 +24,11 @@
class LibraryDocBuilder(object):
-
- def build(self, library, arguments=None):
- lib = TestLibrary(self._normalize_library_path(library), arguments)
+ _argument_separator = '::'
+
+ def build(self, library):
+ name, args = self._split_library_name_and_args(library)
+ lib = TestLibrary(name, args)
libdoc = LibraryDoc(name=lib.name,
doc=self._get_doc(lib),
version=lib.version,
@@ -36,6 +38,11 @@
libdoc.keywords = KeywordDocBuilder().build_keywords(lib)
return libdoc
+ def _split_library_name_and_args(self, library):
+ args = library.split(self._argument_separator)
+ name = args.pop(0)
+ return self._normalize_library_path(name), args
+
def _normalize_library_path(self, library):
path = library.replace('/', os.sep)
if os.path.exists(path):
@@ -59,7 +66,7 @@
class ResourceDocBuilder(object):
- def build(self, path, arguments=None):
+ def build(self, path):
res = self._import_resource(path)
libdoc = LibraryDoc(name=res.name, doc=self._get_doc(res),
type='resource', named_args=True)
=======================================
--- /src/robot/libdocpkg/specbuilder.py Tue Feb 14 05:38:50 2012
+++ /src/robot/libdocpkg/specbuilder.py Mon Feb 20 12:54:34 2012
@@ -21,7 +21,7 @@
class SpecDocBuilder(object):
- def build(self, path, arguments=None):
+ def build(self, path):
spec = self._parse_spec(path)
libdoc = LibraryDoc(name=spec.get('name'),
type=spec.get('type'),
==============================================================================
Revision: c89923d37afc
Author: Pekka Klärck
Date: Mon Feb 20 13:49:20 2012
Log: UG: new target when discussing libdoc
http://code.google.com/p/robotframework/source/detail?r=c89923d37afc
Modified:
/doc/userguide/src/CreatingTestData/CreatingTestCases.txt
/doc/userguide/src/CreatingTestData/CreatingUserKeywords.txt
/doc/userguide/src/CreatingTestData/ResourceAndVariableFiles.txt
/doc/userguide/src/ExtendingRobotFramework/CreatingTestLibraries.txt
/doc/userguide/src/ExtendingRobotFramework/RemoteLibrary.txt
/doc/userguide/src/RobotFrameworkUserGuide.txt
=======================================
--- /doc/userguide/src/CreatingTestData/CreatingTestCases.txt Mon Feb 7
00:59:13 2011
+++ /doc/userguide/src/CreatingTestData/CreatingTestCases.txt Mon Feb 20
13:49:20 2012
@@ -130,7 +130,7 @@
implementation, and typically the best place to search this
information is keyword's documentation. In the examples in this
section the documentation is expected to be generated using the
-`libdoc.py`_ tool, but the same information is available on
+`libdoc`_ tool, but the same information is available on
documentation generated by generic documentation tools such as
:prog:`javadoc`.
=======================================
--- /doc/userguide/src/CreatingTestData/CreatingUserKeywords.txt Wed Jun 29
05:53:04 2011
+++ /doc/userguide/src/CreatingTestData/CreatingUserKeywords.txt Mon Feb 20
13:49:20 2012
@@ -93,7 +93,7 @@
:opt:`[Documentation]` setting, exactly as `test case
documentation`_. This setting documents the user keyword in the test
data. It is also shown in a more formal keyword documentation, which
-the `libdoc.py`_ tool can create from `resource files`_. Finally, the
+the `libdoc`_ tool can create from `resource files`_. Finally, the
first line of the documentation, everything until the first :code:`\\n`
sequence, is shown as a keyword documentation in test logs.
=======================================
--- /doc/userguide/src/CreatingTestData/ResourceAndVariableFiles.txt Mon
Jul 12 04:37:19 2010
+++ /doc/userguide/src/CreatingTestData/ResourceAndVariableFiles.txt Mon
Feb 20 13:49:20 2012
@@ -80,7 +80,7 @@
the resource file itself can have :opt:`Documentation` in the Setting
table similarly as `test suites`__.
-Both `libdoc.py`_ and `RIDE`_ use these documentations, and they
+Both `libdoc`_ and `RIDE`_ use these documentations, and they
are naturally available for anyone opening resource files. The
first line of the documentation of a keyword is logged when it is run,
but otherwise resource file documentations are ignored during the test
=======================================
--- /doc/userguide/src/ExtendingRobotFramework/CreatingTestLibraries.txt
Thu Nov 10 04:06:22 2011
+++ /doc/userguide/src/ExtendingRobotFramework/CreatingTestLibraries.txt
Mon Feb 20 13:49:20 2012
@@ -275,7 +275,7 @@
When a test library is taken into use, Robot Framework tries to
determine its version. This information is then written into the syslog_
to provide debugging information. Library documentation tool
-`libdoc.py`_ also writes this information into the keyword
+`libdoc`_ also writes this information into the keyword
documentations it generates.
Version information is read from attribute
@@ -1237,7 +1237,7 @@
Both Python and Java have tools for creating an API documentation of a
library documented as above. However, outputs from these tools can be
slightly
technical for some users. Another alternative is using Robot
-Framework's own documentation tool `libdoc.py`_. This tool can
+Framework's own documentation tool `libdoc`_. This tool can
create a library documentation from both Python and Java libraries
using the static library API, such as the ones above, but it also handles
libraries using the `dynamic library API`_ and `hybrid library API`_.
@@ -1245,7 +1245,7 @@
The first line of a keyword documentation is used for a special
purpose and should contain a short overall description of the
keyword. It is used as a *short documentation*, for example as a tool
-tip, by `libdoc.py`_ and also shown in the test logs. However, the latter
+tip, by `libdoc`_ and also shown in the test logs. However, the latter
does not work with Java libraries using the static API,
because their documentations are lost in compilation and not available
at runtime.
@@ -1357,7 +1357,7 @@
will most likely get the name of the new keyword from the
documentation so that it searches words inside backticks
(:code:`\``). Thus it would find :name:`Other Keyword` from the
-earlier example. Note that `libdoc.py`_ also automatically creates
+earlier example. Note that `libdoc`_ also automatically creates
internal links using the same syntax.
__ `Documenting libraries`_
@@ -1520,7 +1520,7 @@
The actual argument names do not matter when tests are executed,
because only argument counts are of concern to Robot Framework. On the
-other hand, if the `libdoc.py`_ tool is used for documenting the
+other hand, if the `libdoc`_ tool is used for documenting the
library, arguments are shown in the documentation, in which case they
need to have meaningful names.
@@ -1536,7 +1536,7 @@
The returned documentation is used similarly as the keyword
documentation string with static libraries implemented with
Python. The main use case is getting keywords' documentations into a
-library documentation generated with `libdoc.py`_. Additionally,
+library documentation generated with `libdoc`_. Additionally,
the first line of the documentation (until the first :code:`\\n`) is
shown in test logs.
@@ -1546,14 +1546,14 @@
The :code:`get_keyword_documentation` method can also be used for
specifying overall library documentation. This documentation is not
used when tests are executed, but it can make the documentation
-generated by `libdoc.py`_ much better.
+generated by `libdoc`_ much better.
Dynamic libraries can provide both general library documentation and
documentation related to taking the library into use. The former is
got by calling :code:`get_keyword_documentation` with special value
:code:`__intro__`, and the latter is got using value
:code:`__init__`. How the documentation is presented is best tested
-with `libdoc.py`_ in practice.
+with `libdoc`_ in practice.
Python based dynamic libraries can also specify the general library
documentation directly in the code as the docstring of the library
=======================================
--- /doc/userguide/src/ExtendingRobotFramework/RemoteLibrary.txt Mon Sep 19
14:36:20 2011
+++ /doc/userguide/src/ExtendingRobotFramework/RemoteLibrary.txt Mon Feb 20
13:49:20 2012
@@ -222,7 +222,7 @@
Starting from Robot Framework 2.6.2, remote servers can also provide
`general library documentation`__ to be used when generating
-documenation with `libdoc.py`_ tool.
+documenation with `libdoc`_ tool.
__ `Getting keyword arguments`_
__ `Getting keyword documentation`_
=======================================
--- /doc/userguide/src/RobotFrameworkUserGuide.txt Wed Feb 15 02:18:28 2012
+++ /doc/userguide/src/RobotFrameworkUserGuide.txt Mon Feb 20 13:49:20 2012
@@ -219,8 +219,6 @@
.. _HTML formatting: `Documentation formatting`_
.. _command line options: `All command line options`_
-.. _libdoc.py: ../../tools/libdoc/doc/libdoc.html
-.. _libdoc: `libdoc.py`_
.. _testdoc.py: ../../tools/testdoc/doc/testdoc.html
.. _risto.py: ../../tools/ristopy/doc/ristopy.html
.. _robotidy.py: ../../tools/robotidy/doc/robotidy.html
==============================================================================
Revision: 96d58fa899a3
Author: Pekka Klärck
Date: Mon Feb 20 13:49:57 2012
Log: UG: explicit link target for tidy
http://code.google.com/p/robotframework/source/detail?r=96d58fa899a3
Modified:
/doc/userguide/src/SupportingTools/Tidy.txt
=======================================
--- /doc/userguide/src/SupportingTools/Tidy.txt Wed Feb 15 02:18:28 2012
+++ /doc/userguide/src/SupportingTools/Tidy.txt Mon Feb 20 13:49:57 2012
@@ -1,3 +1,5 @@
+.. _tidy:
+
Test data clean-up tool (:prog:`tidy`)
--------------------------------------
==============================================================================
Revision: bad1e50ef35d
Author: Pekka Klärck
Date: Mon Feb 20 14:11:34 2012
Log: UG/Tidy: Reorganized
http://code.google.com/p/robotframework/source/detail?r=bad1e50ef35d
Modified:
/doc/userguide/src/SupportingTools/Tidy.txt
=======================================
--- /doc/userguide/src/SupportingTools/Tidy.txt Mon Feb 20 13:49:57 2012
+++ /doc/userguide/src/SupportingTools/Tidy.txt Mon Feb 20 14:11:34 2012
@@ -11,8 +11,11 @@
stream, but it can also be redirected to a file. Alternatively, files can
be
modified in-place using :opt:`--inplace` or :opt:`--recursive` options.
+General usage
+~~~~~~~~~~~~~
+
Synopsis
-~~~~~~~~
+''''''''
::
@@ -22,7 +25,7 @@
python -m robot.tidy --recursive [options] directory
Options
-~~~~~~~
+'''''''
-i, --inplace Tidy given file(s) so that original file(s) are
overwritten
(or removed, if the format is changed). When this option
is
@@ -40,6 +43,28 @@
-p, --use-pipes Use a pipe character (|) as a cell separator in the txt
format.
-h, --help Show this help.
+Alternative execution
+'''''''''''''''''''''
+
+:prog:`tidy` is used only with Python in the synopsis and examples above,
+but it works also with Jython and IronPython.
+
+In addition to executing :prog:`tidy` as a module (:cli:`python -m
robot.tidy`),
+it is possible to execute it as a script::
+
+ python path/robot/tidy.py [options] inputfile
+
+This is useful if you have done a `manual installation`_ of the framework
+and just have the :path:`robot` directory with the source code somewhere
+in your system.
+
+Output encoding
+'''''''''''''''
+
+All output files are written using UTF-8 encoding. Outputs written to the
+console use the current console encoding.
+
+
Cleaning up the test data
~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -64,24 +89,3 @@
python -m robot.tidy --format tsv tests_in_html.html > tests_in_tsv.tsv
python -m robot.tidy --format txt --recursive mytests
-
-Output encoding
-~~~~~~~~~~~~~~~
-
-All output files are written using UTF-8 encoding. Outputs written to the
-console use the current console encoding.
-
-Alternative execution
-~~~~~~~~~~~~~~~~~~~~~
-
-:prog:`tidy` is used only with Python in the synopsis and examples above,
-but it works also with Jython and IronPython.
-
-In addition to executing :prog:`tidy` as a module (:cli:`python -m
robot.tidy`),
-it is possible to execute it as a script::
-
- python path/robot/tidy.py [options] inputfile
-
-This is useful if you have done a `manual installation`_ of the framework
-and just have the :path:`robot` directory with the source code somewhere
-in your system.
==============================================================================
Revision: 306199db9384
Author: Pekka Klärck
Date: Mon Feb 20 14:17:53 2012
Log: UG/Libdoc: Clean-up, enhancements, and re-organization.
Updata issue 1028
I did some more enhancements to the doc in UG. There were so many changes
that another review would be nice. Otherwise I consider the documentation,
and this issue, done.
http://code.google.com/p/robotframework/source/detail?r=306199db9384
Modified:
/doc/userguide/src/SupportingTools/Libdoc.txt
=======================================
--- /doc/userguide/src/SupportingTools/Libdoc.txt Fri Feb 17 10:49:33 2012
+++ /doc/userguide/src/SupportingTools/Libdoc.txt Mon Feb 20 14:17:53 2012
@@ -1,3 +1,5 @@
+.. _libdoc:
+
Library documentation tool (:prog:`libdoc`)
-------------------------------------------
@@ -7,31 +9,37 @@
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.
+- test libraries implemented with Python__ or Java__ using the normal
+ static library API,
+- test libraries using the `dynamic API`__, including remote libraries, and
+- `resource files`_.
+
+Additionally it is possible to use XML spec created by :prog:`libdoc`
+earlier as an input.
+
+:prog:`libdoc` is built-in into Robot Framework and automatically included
+in the installation starting from version 2.7. With earlier versions you
+need to download `libdoc.py script`__ separately. The command line usage
+has changed slightly between these versions but the documentation syntax
+is still the same.
__ `Python libraries`_
__ `Java libraries`_
__ `Dynamic libraries`_
-
-:prog:`libdoc` is built-in into Robot Framework and automatically included
-in the installation starting from version 2.7.
-
+__ http://code.google.com/p/robotframework/wiki/LibraryDocumentationTool
+
+General usage
+~~~~~~~~~~~~~
Synopsis
-~~~~~~~~
+''''''''
::
python -m robot.libdoc [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
@@ -39,9 +47,8 @@
-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.
+ -P, --pythonpath <path> Additional locations where to search for
libraries
+ and resources similarly as when `running
tests`__.
-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.
@@ -50,53 +57,58 @@
-h, --help Prints this help.
-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).
+__ `Using --pythonpath option`_
+
+Specifying library or resource file
+'''''''''''''''''''''''''''''''''''
+
+Python libraries and dynamic libraries with name or path
+````````````````````````````````````````````````````````
+
+When documenting libraries implemented with Python or that use the
+dynamic library API, it is possible to specify the library either by
+using just the library name or path to the library source code.
+In the former case the library is searched using the `library search path`_
+and its name must be in the same format as in Robot Framework test data.
+
+If these libraries require arguments when they are imported, the arguments
+must be catenated with the library name or path using two colons like
+:cli:`MyLibrary::arg1::arg2`. If arguments change what keywords the library
+provides or otherwise alter its documentation, it might be a good idea to
use
+:opt:`--name` option to also change the library name accordingly.
+
+Java libraries with path
+````````````````````````
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.
+of the Java JDK distribution, must be found from CLASSPATH when
+:prog:`libdoc` is executed. Notice that generating documentation for Java
+libraries works only with Jython.
+
+Resource files with path
+````````````````````````
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.
+PYTHONPATH similarly as when executing test cases.
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 --name MyLibrary Remote::http://10.0.0.42:8270
MyLibrary.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
+ jython -m robot.libdoc --version 1.0 MyJavaLibrary.java
MyJavaLibrary.xml
Alternative execution
-~~~~~~~~~~~~~~~~~~~~~
+'''''''''''''''''''''
:prog:`libdoc` works with all supported interpreters, although creating
-documentation from java source files requires running :prog:`libdoc` with
-:prog:`jython`.
+documentation from Java source files requires running :prog:`libdoc` with
+Jython.
In addition to executing :prog:`libdoc` as a module
(:cli:`python -m robot.libdoc`), it is possible to execute it as a script::
@@ -126,14 +138,14 @@
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
-strings, see `PEP-257`_.
+strings, see `PEP-257`__.
.. sourcecode:: python
class ExampleLib:
"""Library for demo purposes.
- This library is only used in an example and it does't do anything
useful.
+ This library is only used in an example and it doesn't do anything
useful.
"""
def my_keyword(self):
@@ -153,6 +165,7 @@
Python libraries, you must either use UTF-8 as your `source code
encoding`__ or create docstrings as Unicode.
+__ http://www.python.org/dev/peps/pep-0257
__ http://www.python.org/dev/peps/pep-0263
Java libraries
@@ -160,7 +173,7 @@
When writing documentation for a normal Java library, conventions for
writing Javadoc should be used. The documentation is generated based
-on the Javadocs in the source files. For example following simple
+on the Javadocs in the source files. For example, the following simple
example has exactly same documentation (and functionality) than the
earlier Python example.
@@ -169,12 +182,12 @@
/**
* Library for demo purposes.
*
- * This library is only used in an example and it does't do anything
useful.
+ * This library is only used in an example and it doesn't do anything
useful.
*/
public class ExampleLib {
/**
- * Does nothing
+ * Does nothing.
*/
public void myKeyword() {
}
@@ -209,9 +222,9 @@
A separate section about how the library is imported is created based on
its
initialization methods. For a Python library, if it has
an :code:`__init__`
-method that takes arguments in addition to :code:`self`, the documentation
of
-that method is shown. For a Java library, if it has a constructor that
accepts
-arguments, all its constructors and their javadocs are shown.
+method that takes arguments in addition to :code:`self`, its documentation
and
+arguments are shown. For a Java library, if it has a public constructor
that
+accepts arguments, all its public constructors are shown.
.. sourcecode:: python
@@ -230,7 +243,7 @@
Keywords in resource files can have documentation using
:opt:`[Documentation]` setting, and this documentation is also used by
-:prog:`libdoc.py`. First line of the documentation (until the first
+:prog:`libdoc`. First line of the documentation (until the first
:code:`\\n`) is considered to be the short documentation similarly as
with test libraries.
@@ -242,13 +255,13 @@
.. table:: An example resource file
:class: example
-
+---------------+-----------------------------------------+----------------------------------+
- | Setting | Value
| Value |
-
+===============+=========================================+==================================+
- | Documentation | Resource file for demo purposes.\\n
| |
-
+---------------+-----------------------------------------+----------------------------------+
- | ... | This resource is only used in an example| and it
does't do anything useful.|
-
+---------------+-----------------------------------------+----------------------------------+
+
+---------------+-----------------------------------------+-----------------------------------+
+ | Setting | Value
| Value |
+
+===============+=========================================+===================================+
+ | Documentation | Resource file for demo purposes.\\n
| |
+
+---------------+-----------------------------------------+-----------------------------------+
+ | ... | This resource is only used in an example| and it
doesn't do anything useful.|
+
+---------------+-----------------------------------------+-----------------------------------+
.. table::
:class: example
@@ -272,24 +285,24 @@
+--------------+------------------+------------------------+-------------------------------+
Documentation syntax
-~~~~~~~~~~~~~~~~~~~~
+''''''''''''''''''''
Generic formatting rules
-''''''''''''''''''''''''
-
-Most important features of `documentation formatting`_ are formatting using
+````````````````````````
+
+The documentation is generated according to Robot Framework's
`documentation
+formatting`_ rules. Most important features of are formatting using
:code:`*bold*` and :code:`_italic_`, automatic conversion of URLs to
-clickable links, and the possibility to create tables and blocks (useful
for
-examples) simply with pipe character.
+clickable links, and the possibility to create tables and pre-formatted
blocks
+(useful for examples) simply with pipe character.
Special formatting and internal linking
-'''''''''''''''''''''''''''''''''''''''
-
-In addition to the formatting explained in the specific section,
-:prog:`libdoc.py` supports also special formatting of keyword names
+```````````````````````````````````````
+
+:prog:`libdoc` supports also special formatting of keyword names
and arguments with backtick character :code:`\``. Even more
importantly, this syntax also automatically creates internal links to
-other keywords in the library. For example documentation of the
+other keywords in the library. For example, documentation of the
following simple Python library would have link from :name:`Log
Messages` to :name:`Log Message`, and :code:`\`message\`` and
:code:`\`level\`` would be formatted specially.
@@ -313,8 +326,8 @@
log_message(message1, level)
log_message(message2, level)
-Additionally, using :code:`\`introduction\`` or :code:`\`library
introduction\``
-(case insensitive) generates a link to the library introduction in the
beginning
+Additionally, using :code:`\`introduction\`` or :code:`\`library
introduction\``,
+case insensitively, generates a link to the library introduction in the
beginning
of the generated documentation. Similarly :code:`\`importing\``
or :code:`\`library importing\`` generates a link to the `importing
section`_.
@@ -323,16 +336,10 @@
realistic example.
Keywords' arguments
-'''''''''''''''''''
-
-:prog:`libdoc.py` handles keywords' arguments automatically so that
+```````````````````
+
+:prog:`libdoc` handles keywords' arguments automatically so that
arguments specified for methods in libraries or user keywords in
-resource files are listed in a separate column. Possible trailing
-underscores in argument names are stripped to make it possible to use
-arguments like :code:`list_` in the code and still have :code:`list`
-in documentation. Additionally, user keyword arguments are shown
-without :var:`${}` or :var:`@{}` to make arguments look the same
-regardless where keywords originated from.
-
-
-.. _PEP-257: http://www.python.org/dev/peps/pep-0257
+resource files are listed in a separate column. User keyword arguments
+are shown without :var:`${}` or :var:`@{}` to make arguments look
+the same regardless where keywords originated from.
