Author: janne.t.harkonen
Date: Wed Nov 19 03:16:58 2008
New Revision: 998
Added:
trunk/tools/testdoc/doc/
trunk/tools/testdoc/doc/testdoc.html
trunk/tools/testdoc/doc/testdoc.txt (contents, props changed)
Log:
Added rst documentation for testdoc
Added: trunk/tools/testdoc/doc/testdoc.html
==============================================================================
--- (empty file)
+++ trunk/tools/testdoc/doc/testdoc.html Wed Nov 19 03:16:58 2008
@@ -0,0 +1,590 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0
Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd";>
+<html xmlns="http://www.w3.org/1999/xhtml"; xml:lang="en" lang="en">
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+<meta name="generator" content="Docutils 0.5:
http://docutils.sourceforge.net/"; />
+<title>testdoc.py</title>
+<style type="text/css">
+
+/* Robot Framework User Guide Style Sheet
+
+ This stylesheet contains styles from restructuredText's default
+ 'html4css1.css' and after that modifications needed for Robot Framework
User
+ Guide. These styles are added into the same file against suggestions at
+ reST's stylesheet howto mentioned below, because we want to be able to
+ embed all styles into the created HTML file. Everything before 'Robot
+ Framework User Guide Modifications' text is from 'html4css1.css' without
+ any changes so that part can still be changed easily.
+*/
+
+
+/*
+:Author: David Goodger ([EMAIL PROTECTED])
+:Id: $Id: html4css1.css 5196 2007-06-03 20:25:28Z wiemann $
+:Copyright: This stylesheet has been placed in the public domain.
+
+Default cascading style sheet for the HTML output of Docutils.
+
+See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to
+customize this style sheet.
+*/
+
+/* used to remove borders from tables and images */
+.borderless, table.borderless td, table.borderless th {
+ border: 0 }
+
+table.borderless td, table.borderless th {
+ /* Override padding for "table.docutils td" with "! important".
+ The right padding separates the table cells. */
+ padding: 0 0.5em 0 0 ! important }
+
+.first {
+ /* Override more specific margin styles with "! important". */
+ margin-top: 0 ! important }
+
+.last, .with-subtitle {
+ margin-bottom: 0 ! important }
+
+.hidden {
+ display: none }
+
+a.toc-backref {
+ text-decoration: none ;
+ color: black }
+
+blockquote.epigraph {
+ margin: 2em 5em ; }
+
+dl.docutils dd {
+ margin-bottom: 0.5em }
+
+/* Uncomment (and remove this text!) to get bold-faced definition list
terms
+dl.docutils dt {
+ font-weight: bold }
+*/
+
+div.abstract {
+ margin: 2em 5em }
+
+div.abstract p.topic-title {
+ font-weight: bold ;
+ text-align: center }
+
+div.admonition, div.attention, div.caution, div.danger, div.error,
+div.hint, div.important, div.note, div.tip, div.warning {
+ margin: 2em ;
+ border: medium outset ;
+ padding: 1em }
+
+div.admonition p.admonition-title, div.hint p.admonition-title,
+div.important p.admonition-title, div.note p.admonition-title,
+div.tip p.admonition-title {
+ font-weight: bold ;
+ font-family: sans-serif }
+
+div.attention p.admonition-title, div.caution p.admonition-title,
+div.danger p.admonition-title, div.error p.admonition-title,
+div.warning p.admonition-title {
+ color: red ;
+ font-weight: bold ;
+ font-family: sans-serif }
+
+/* Uncomment (and remove this text!) to get reduced vertical space in
+ compound paragraphs.
+div.compound .compound-first, div.compound .compound-middle {
+ margin-bottom: 0.5em }
+
+div.compound .compound-last, div.compound .compound-middle {
+ margin-top: 0.5em }
+*/
+
+div.dedication {
+ margin: 2em 5em ;
+ text-align: center ;
+ font-style: italic }
+
+div.dedication p.topic-title {
+ font-weight: bold ;
+ font-style: normal }
+
+div.figure {
+ margin-left: 2em ;
+ margin-right: 2em }
+
+div.footer, div.header {
+ clear: both;
+ font-size: smaller }
+
+div.line-block {
+ display: block ;
+ margin-top: 1em ;
+ margin-bottom: 1em }
+
+div.line-block div.line-block {
+ margin-top: 0 ;
+ margin-bottom: 0 ;
+ margin-left: 1.5em }
+
+div.sidebar {
+ margin: 0 0 0.5em 1em ;
+ border: medium outset ;
+ padding: 1em ;
+ background-color: #ffffee ;
+ width: 40% ;
+ float: right ;
+ clear: right }
+
+div.sidebar p.rubric {
+ font-family: sans-serif ;
+ font-size: medium }
+
+div.system-messages {
+ margin: 5em }
+
+div.system-messages h1 {
+ color: red }
+
+div.system-message {
+ border: medium outset ;
+ padding: 1em }
+
+div.system-message p.system-message-title {
+ color: red ;
+ font-weight: bold }
+
+div.topic {
+ margin: 2em }
+
+h1.section-subtitle, h2.section-subtitle, h3.section-subtitle,
+h4.section-subtitle, h5.section-subtitle, h6.section-subtitle {
+ margin-top: 0.4em }
+
+h1.title {
+ text-align: center }
+
+h2.subtitle {
+ text-align: center }
+
+hr.docutils {
+ width: 75% }
+
+img.align-left {
+ clear: left }
+
+img.align-right {
+ clear: right }
+
+ol.simple, ul.simple {
+ margin-bottom: 1em }
+
+ol.arabic {
+ list-style: decimal }
+
+ol.loweralpha {
+ list-style: lower-alpha }
+
+ol.upperalpha {
+ list-style: upper-alpha }
+
+ol.lowerroman {
+ list-style: lower-roman }
+
+ol.upperroman {
+ list-style: upper-roman }
+
+p.attribution {
+ text-align: right ;
+ margin-left: 50% }
+
+p.caption {
+ font-style: italic }
+
+p.credits {
+ font-style: italic ;
+ font-size: smaller }
+
+p.label {
+ white-space: nowrap }
+
+p.rubric {
+ font-weight: bold ;
+ font-size: larger ;
+ color: maroon ;
+ text-align: center }
+
+p.sidebar-title {
+ font-family: sans-serif ;
+ font-weight: bold ;
+ font-size: larger }
+
+p.sidebar-subtitle {
+ font-family: sans-serif ;
+ font-weight: bold }
+
+p.topic-title {
+ font-weight: bold }
+
+pre.address {
+ margin-bottom: 0 ;
+ margin-top: 0 ;
+ font-family: serif ;
+ font-size: 100% }
+
+pre.literal-block, pre.doctest-block {
+ margin-left: 2em ;
+ margin-right: 2em }
+
+span.classifier {
+ font-family: sans-serif ;
+ font-style: oblique }
+
+span.classifier-delimiter {
+ font-family: sans-serif ;
+ font-weight: bold }
+
+span.interpreted {
+ font-family: sans-serif }
+
+span.option {
+ white-space: nowrap }
+
+span.pre {
+ white-space: pre }
+
+span.problematic {
+ color: red }
+
+span.section-subtitle {
+ /* font-size relative to parent (h1..h6 element) */
+ font-size: 80% }
+
+table.citation {
+ border-left: solid 1px gray;
+ margin-left: 1px }
+
+table.docinfo {
+ margin: 2em 4em }
+
+table.docutils {
+ margin-top: 0.5em ;
+ margin-bottom: 0.5em }
+
+table.footnote {
+ border-left: solid 1px black;
+ margin-left: 1px }
+
+table.docutils td, table.docutils th,
+table.docinfo td, table.docinfo th {
+ padding-left: 0.5em ;
+ padding-right: 0.5em ;
+ vertical-align: top }
+
+table.docutils th.field-name, table.docinfo th.docinfo-name {
+ font-weight: bold ;
+ text-align: left ;
+ white-space: nowrap ;
+ padding-left: 0 }
+
+h1 tt.docutils, h2 tt.docutils, h3 tt.docutils,
+h4 tt.docutils, h5 tt.docutils, h6 tt.docutils {
+ font-size: 100% }
+
+ul.auto-toc {
+ list-style-type: none }
+
+
+/* **************************************** *
+ * Robot Framework User Guide Modifications *
+ * **************************************** */
+
+/* Tables
+ - example, tsv-example: test data examples
+ - messages: log message examples
+ - tabular: normal tabular information
+*/
+table.example, table.tsv-example, table.messages, table.tabular {
+ border: 1px solid #808080;
+ border-collapse: collapse;
+ empty-cell: show;
+ margin: 0.5em 2em;
+}
+table.example caption, table.tsv-example caption, table.tabular caption {
+ text-align: left;
+ padding-bottom: 0.5em;
+ font-style: italic;
+ margin: 0.5em 2em;
+}
+table.example th, table.example td, table.tsv-example td {
+ border: 1px solid #808080;
+ font-family: arial,helvetica,sans-serif;
+ height: 1.2em;
+ font-size: 0.85em;
+}
+table.example th {
+ padding: 0.1em 1em;
+ background: #E0E0E0;
+}
+table.example td, table.tsv-example td {
+ padding: 0.1em 1em 0.1em 0.3em;
+}
+table.tabular th, table.tabular td {
+ border: 1px solid black;
+ padding: 0.1em 0.3em;
+ height: 1.2em;
+ font-size: 0.9em;
+}
+table.messages {
+ border: 1px solid gray;
+ font-family: monospace;
+ margin: 1em 2em;
+ width: 60%;
+}
+table.messages td {
+ vertical-align: top;
+ padding: 0.1em 0.2em;
+}
+table.messages td.time {
+ width: 7em;
+ letter-spacing: -0.05em;
+}
+table.messages td.level {
+ width: 5em;
+ text-align: center;
+}
+table.messages td.fail, table.messages td.error {
+ color: red;
+}
+table.messages td.pass {
+ color: #009900;
+}
+table.messages td.warn {
+ color: #FFCC00;
+}
+
+/* Roles -- these are defined in roles.txt file */
+
+.var {
+ background: #f4f4f4;
+ font-size: 0.9em;
+}
+.opt {
+ font-style: italic;
+}
+.prog, .code, .cli {
+ background: #f4f4f4;
+ font-family: monospace;
+}
+.msg {
+ font-family: monospace;
+}
+.name {
+ font-style: italic;
+}
+.path {
+ font-style: italic;
+}
+.misc, .literal {
+ background: #f4f4f4;
+}
+
+
+/* Overridden and modified styles */
+
+div.admonition, div.attention, div.caution, div.danger, div.error,
+div.hint, div.important, div.note, div.tip, div.warning {
+ border: 2px solid gray;
+}
+pre.literal-block, pre.doctest-block {
+ background: #f4f4f4;
+}
+
+
+/* Pygments
+
+- Styles generated using "HtmlFormatter().get_style_defs('.highlight')"
+- Changed only background (f8f8f8 -> f4f4f4) and added margin
+- For more details see e.g. http://pygments.org/docs/quickstart/
+*/
+
+.highlight { background: #f4f4f4; margin: 1em 2em; }
+.highlight .c { color: #408080; font-style: italic } /* Comment */
+.highlight .err { border: 1px solid #FF0000 } /* Error */
+.highlight .k { color: #008000; font-weight: bold } /* Keyword */
+.highlight .o { color: #666666 } /* Operator */
+.highlight .cm { color: #408080; font-style: italic } /* Comment.Multiline
*/
+.highlight .cp { color: #BC7A00 } /* Comment.Preproc */
+.highlight .c1 { color: #408080; font-style: italic } /* Comment.Single */
+.highlight .cs { color: #408080; font-style: italic } /* Comment.Special */
+.highlight .gd { color: #A00000 } /* Generic.Deleted */
+.highlight .ge { font-style: italic } /* Generic.Emph */
+.highlight .gr { color: #FF0000 } /* Generic.Error */
+.highlight .gh { color: #000080; font-weight: bold } /* Generic.Heading */
+.highlight .gi { color: #00A000 } /* Generic.Inserted */
+.highlight .go { color: #808080 } /* Generic.Output */
+.highlight .gp { color: #000080; font-weight: bold } /* Generic.Prompt */
+.highlight .gs { font-weight: bold } /* Generic.Strong */
+.highlight .gu { color: #800080; font-weight: bold } /* Generic.Subheading
*/
+.highlight .gt { color: #0040D0 } /* Generic.Traceback */
+.highlight .kc { color: #008000; font-weight: bold } /* Keyword.Constant */
+.highlight .kd { color: #008000; font-weight: bold } /*
Keyword.Declaration */
+.highlight .kp { color: #008000 } /* Keyword.Pseudo */
+.highlight .kr { color: #008000; font-weight: bold } /* Keyword.Reserved */
+.highlight .kt { color: #B00040 } /* Keyword.Type */
+.highlight .m { color: #666666 } /* Literal.Number */
+.highlight .s { color: #BA2121 } /* Literal.String */
+.highlight .na { color: #7D9029 } /* Name.Attribute */
+.highlight .nb { color: #008000 } /* Name.Builtin */
+.highlight .nc { color: #0000FF; font-weight: bold } /* Name.Class */
+.highlight .no { color: #880000 } /* Name.Constant */
+.highlight .nd { color: #AA22FF } /* Name.Decorator */
+.highlight .ni { color: #999999; font-weight: bold } /* Name.Entity */
+.highlight .ne { color: #D2413A; font-weight: bold } /* Name.Exception */
+.highlight .nf { color: #0000FF } /* Name.Function */
+.highlight .nl { color: #A0A000 } /* Name.Label */
+.highlight .nn { color: #0000FF; font-weight: bold } /* Name.Namespace */
+.highlight .nt { color: #008000; font-weight: bold } /* Name.Tag */
+.highlight .nv { color: #19177C } /* Name.Variable */
+.highlight .ow { color: #AA22FF; font-weight: bold } /* Operator.Word */
+.highlight .w { color: #bbbbbb } /* Text.Whitespace */
+.highlight .mf { color: #666666 } /* Literal.Number.Float */
+.highlight .mh { color: #666666 } /* Literal.Number.Hex */
+.highlight .mi { color: #666666 } /* Literal.Number.Integer */
+.highlight .mo { color: #666666 } /* Literal.Number.Oct */
+.highlight .sb { color: #BA2121 } /* Literal.String.Backtick */
+.highlight .sc { color: #BA2121 } /* Literal.String.Char */
+.highlight .sd { color: #BA2121; font-style: italic } /*
Literal.String.Doc */
+.highlight .s2 { color: #BA2121 } /* Literal.String.Double */
+.highlight .se { color: #BB6622; font-weight: bold } /*
Literal.String.Escape */
+.highlight .sh { color: #BA2121 } /* Literal.String.Heredoc */
+.highlight .si { color: #BB6688; font-weight: bold } /*
Literal.String.Interpol */
+.highlight .sx { color: #008000 } /* Literal.String.Other */
+.highlight .sr { color: #BB6688 } /* Literal.String.Regex */
+.highlight .s1 { color: #BA2121 } /* Literal.String.Single */
+.highlight .ss { color: #19177C } /* Literal.String.Symbol */
+.highlight .bp { color: #008000 } /* Name.Builtin.Pseudo */
+.highlight .vc { color: #19177C } /* Name.Variable.Class */
+.highlight .vg { color: #19177C } /* Name.Variable.Global */
+.highlight .vi { color: #19177C } /* Name.Variable.Instance */
+.highlight .il { color: #666666 } /* Literal.Number.Integer.Long */
+
+</style>
+</head>
+<body>
+<div class="document" id="testdoc-py">
+<h1 class="title">testdoc.py</h1>
+
+<!-- Roles to use in text like :rolename:`text`. Styled in userguide.css.
+- var variables
+- opt settings in setting table (e.g. Force Tags), tc/kw tables
+ (e.g [Documentation]) and command line options (e.g. - -name)
+- prog program names (e.g. rebot, risto.py)
+- code programming code
+- msg test case status and message, as well as log messages and levels
+- name keyword, library, test case, test suite, etc. names
+- cli command line examples (note that options alone use opt)
+- path file names and paths
+- misc everything else (synonym to ``text``) -->
+<p><span class="prog">testdoc.py</span> is a tool for generating a high
level documentation from
+Robot Framework test data. It is included in source distributions and can
also
+be downloaded from <a class="reference external"
href="http://code.google.com/p/robotframework/wiki/TestDataDocumentationTool";>http://code.google.com/p/robotframework/wiki/TestDataDocumentationTool</a></p>
+<div class="section" id="synopsis">
+<h1>Synopsis</h1>
+<pre class="literal-block">
+testdoc.py [options] data_sources
+</pre>
+</div>
+<div class="section" id="options">
+<h1>Options</h1>
+<blockquote>
+<table class="docutils option-list" frame="void" rules="none">
+<col class="option" />
+<col class="description" />
+<tbody valign="top">
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">-o</span>, <span class="option">--output
<var><path></var></span></kbd></td>
+</tr>
+<tr><td> </td><td>Where to write the generated documentation. If
+the path is a directory, the documentation is
+generated there using name
+'<suitename>-doc.html'.</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">-T</span>, <span class="option">--title
<var><title></var></span></kbd></td>
+</tr>
+<tr><td> </td><td>Set the title of the generated documentation.
+Underscores in the title are converted to spaces.</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">-N</span>, <span class="option">--name
<var><name></var></span></kbd></td>
+</tr>
+<tr><td> </td><td>Set the name of the top level test suite.
+See pybot --help or Robot Framework user guide
+for details.</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">-D</span>, <span class="option">--doc
<var><document></var></span></kbd></td>
+</tr>
+<tr><td> </td><td>Set the document of the top level test suite.
+See pybot --help or Robot Framework user guide
+for details.</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">-M</span>, <span class="option">--metadata
<var><name:value></var></span></kbd></td>
+</tr>
+<tr><td> </td><td>Set metadata of the top level test suite. See
+pybot --help for details.</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">-G</span>, <span class="option">--settag
<var><tag></var></span></kbd></td>
+</tr>
+<tr><td> </td><td>Sets given tag(s) to all executed test
cases.</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">-t</span>, <span class="option">--test
<var><name></var></span></kbd></td>
+</tr>
+<tr><td> </td><td>Select test cases to be included in the
+documentation by name. See pybot --help or Robot
+Framework user guide for details on filtering.</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">-s</span>, <span class="option">--suite
<var><name></var></span></kbd></td>
+</tr>
+<tr><td> </td><td>Select test suites to be included in the
+documentation by name. See pybot --help or Robot
+Framework user guide for details on filtering.</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">-i</span>, <span class="option">--include
<var><tag></var></span></kbd></td>
+</tr>
+<tr><td> </td><td>Select test cases to be included in the
+documentation by tag. See pybot --help or Robot
+Framework user guide for details on filtering.</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">-e</span>, <span class="option">--exclude
<var><tag></var></span></kbd></td>
+</tr>
+<tr><td> </td><td>Select test cases not to be included in the
+documentation by tag. See pybot --help or Robot
+Framework user guide for details on filtering.</td></tr>
+<tr><td class="option-group">
+<kbd><span class="option">-h</span>, <span
class="option">--help</span></kbd></td>
+<td>Print this help in the console.</td></tr>
+</tbody>
+</table>
+</blockquote>
+</div>
+<div class="section" id="description">
+<h1>Description</h1>
+<p>This script compares generates a high level documentation of the given
Robot
+Framework data sources. The generated documentation includes the names of
the
+suites and tests, as well as the names of the toplevel keywords fir each
suite.
+Also the total number of tests per suite is available. It is possible to
select
+suites and tests to be included in the documentation similarly as when
choosing
+the test cases to be executed with Robot Framework. The test data is parsed
+similarly as when executing the tests, but the variables are not
resolved.</p>
+<p>Examples:</p>
+<pre class="literal-block">
+$ testdoc.py mytestcases.html
+$ testdoc.py --name smoke_test_plan --include smoke my_tests
+</pre>
+</div>
+</div>
+<div class="footer">
+<hr class="footer" />
+Generated on: 2008-11-19 11:10 UTC.
+
+</div>
+</body>
+</html>
Added: trunk/tools/testdoc/doc/testdoc.txt
==============================================================================
--- (empty file)
+++ trunk/tools/testdoc/doc/testdoc.txt Wed Nov 19 03:16:58 2008
@@ -0,0 +1,68 @@
+.. include:: ../../../doc/userguide/src/roles.txt
+
+==========
+testdoc.py
+==========
+
+:prog:`testdoc.py` is a tool for generating a high level documentation from
+Robot Framework test data. It is included in source distributions and can
also
+be downloaded from
http://code.google.com/p/robotframework/wiki/TestDataDocumentationTool
+
+Synopsis
+--------
+
+::
+
+ testdoc.py [options] data_sources
+
+
+Options
+-------
+
+ -o, --output <path> Where to write the generated documentation.
If
+ the path is a directory, the documentation
is
+ generated there using name
+ '<suitename>-doc.html'.
+ -T, --title <title> Set the title of the generated
documentation.
+ Underscores in the title are converted to
spaces.
+ -N, --name <name> Set the name of the top level test suite.
+ See pybot --help or Robot Framework user
guide
+ for details.
+ -D, --doc <document> Set the document of the top level test
suite.
+ See pybot --help or Robot Framework user
guide
+ for details.
+ -M, --metadata <name:value> Set metadata of the top level test suite.
See
+ pybot --help for details.
+ -G, --settag <tag> Sets given tag(s) to all executed test
cases.
+ -t, --test <name> Select test cases to be included in the
+ documentation by name. See pybot --help or
Robot
+ Framework user guide for details on
filtering.
+ -s, --suite <name> Select test suites to be included in the
+ documentation by name. See pybot --help or
Robot
+ Framework user guide for details on
filtering.
+ -i, --include <tag> Select test cases to be included in the
+ documentation by tag. See pybot --help or
Robot
+ Framework user guide for details on
filtering.
+ -e, --exclude <tag> Select test cases not to be included in the
+ documentation by tag. See pybot --help or
Robot
+ Framework user guide for details on
filtering.
+ -h, --help Print this help in the console.
+
+
+Description
+-----------
+
+This script compares generates a high level documentation of the given
Robot
+Framework data sources. The generated documentation includes the names of
the
+suites and tests, as well as the names of the toplevel keywords fir each
suite.
+Also the total number of tests per suite is available. It is possible to
select
+suites and tests to be included in the documentation similarly as when
choosing
+the test cases to be executed with Robot Framework. The test data is parsed
+similarly as when executing the tests, but the variables are not resolved.
+
+
+Examples::
+
+ $ testdoc.py mytestcases.html
+ $ testdoc.py --name smoke_test_plan --include smoke my_tests
+
