libdoc documentation for RIDE

[Martin Taylor]

I really like how RIDE can use XML files, generated by libdoc.py from
a test library's code comments, and then have searchable and
displayable keyword documentation. I want to take advantage of this
feature as we roll out our Robot Framework Test Automation to the
entire SQA team at TI. The problem is how to generate the XML files
with libdoc.py in our rather complex test library configuration.

We have a ProductLibrary that provides keywords to test ALL "flavours"
of our product. This library is really a proxy for two other
libraries: DesktopLibrary and DeviceLibrary. Our product runs on PC
or Mac ("Desktop") platforms AND on hand-held devices ("Device"). We
have a single set of tests for common product features that work on
either the Device or Desktop platforms. When the ProductLibrary
(written in Python) is configured for "Desktop" it communicates via
the remote library XML-RPC interface to a Java DesktopLibrary that
drives the Desktop GUI of the product. When ProductLibrary is
configured for "Device" it directly imports the DeviceLibrary (also
written in Python) and proxies for it. The DeviceLibrary sends
keystrokes and other GUI commands to Devices attached to the host PC
or Mac via USB.

There is a core set of keywords that are common to Device and
Desktop. There are also sets of keywords that are specific to Device
or Desktop product flavours respectively. Getting the libdoc.py
documentation for the DeviceLibrary keywords and naming it as
ProductLibrary.xml is fairly simple and we've been doing this for a
while. We're currently experimenting with running libdoc.py via
jython on the DesktopLibrary.jar file and expect to solve that soon.

What we don't know how to do, and would appreciate advice on from the
RIDE user community, is how to integrate these two sets of keyword
documentation into a single ProductLibrary.xml so that RIDE knows
about all keywords supported by either or both of the proxied
DesktopLibrary and DeviceLibrary.

Any suggestions and tips would be greatly appreciated!

Thanks,
Martin Taylor

[Taylor, Martin]

Yes, I use libdoc.py on the proxy ProductLibrary, but it only generates the keyword documentation for the underlying DeviceLibrary. There are 2 reasons for this:

1. ProductLibrary can only proxy for one of the underlying libraries at a time. With its default set of configuration parameters it proxies for the DeviceLibrary.

2. The DesktopLibrary is a remote library written in Java and run under a JVM without using jython. Thus, as far as I know, its get_keyword_documentation method has no way to get the documentation at run time. If there is a way to do this in Java, please let me know 'cause my Java skills are rather lacking.

So, however this is done, I think I'd need to run libdoc.py twice on the same library and then somehow combine the results. That's really the focus of this question to the user group.

Thanks,
Martin

> -----Original Message-----
> From: GerhardH [mailto:gerhard....@nsn.com]
> Sent: Tuesday, March 15, 2011 4:03 AM
> To: Taylor, Martin
> Subject: Re: libdoc documentation for RIDE
>
> Hello Martin,
>
> did you try to call libdoc.py on your proxy ProductLibrary?
>
> I did not quite understand your construction, but I have a
> library to access proprietary GUI controls in our
> application; this library (written in
> Java)
> extends RobotFrameworks SwingLibrary.
>
> When I call libdoc.py -f XML myLibrary, it generates a XML
> file with my own keywords and keywords that are implemented
> in SwingLibrary.
>
> I assume that this could work in your case also.
>
> Best regards
> Gerhard

[Pekka Klärck]

2011/3/15 Taylor, Martin <cmta...@ti.com>:

> So, however this is done, I think I'd need to run libdoc.py twice on the same library and then somehow combine the results.  That's really the focus of this question to the user group.

I think this is the easiest solution. The format of the XML spec files
produced by libdoc.py and understood by RIDE is so simple that
combining them ought to be easy to automate.

Potentially libdoc.py could be enhanced so that it accepts multiple
libraries as an input and produces one combined spec file. This
shouldn't be too complicated but we needed to decide how to handle
the general library documentation. RIDE currently doesn't show that at
all but it's visible in the HTML versions.

Cheers,
.peke
--
Agile Tester/Developer/Consultant :: http://eliga.fi
Lead Developer of Robot Framework :: http://robotframework.org