summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorPetr Šplíchal <psplicha@redhat.com>2012-02-22 11:59:18 +0100
committerPetr Šplíchal <psplicha@redhat.com>2012-02-22 11:59:18 +0100
commit6b809f9ef9418fd43af0864fdf0f95d8c88106a7 (patch)
treef1c3c60cb07833976dded0d9a85f2df0798cfac7
parent9707ada7391985131c26f433339b3a79fb2f393c (diff)
downloadpython-nitrate-6b809f9ef9418fd43af0864fdf0f95d8c88106a7.zip
python-nitrate-6b809f9ef9418fd43af0864fdf0f95d8c88106a7.tar.gz
python-nitrate-6b809f9ef9418fd43af0864fdf0f95d8c88106a7.tar.xz
Generate documentation from reStructuredText
README converted to reStructuredText manual pages now generated dynamically documentation/nitrate.man no more necessary
-rw-r--r--README90
-rw-r--r--documentation/nitrate.man84
-rw-r--r--documentation/nitrate.rst38
3 files changed, 76 insertions, 136 deletions
diff --git a/README b/README
index 4f79fa9..c84a369 100644
--- a/README
+++ b/README
@@ -1,15 +1,27 @@
+======================
+ python-nitrate
+======================
+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Python API for the Nitrate test case management system
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+:Manual section: 1
+:Manual group: User Commands
+:Date: February 2012
+
+
+DESCRIPTION
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
python-nitrate is a Python interface to the Nitrate test case
management system. The package consists of a high-level Python
module (provides natural object interface), a low-level driver
(allows to directly access Nitrate's xmlrpc API) and a command
line interpreter (useful for fast debugging and experimenting).
-Features
+
+FEATURES
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Among the most essential python-nitrate features are:
@@ -22,34 +34,34 @@ Among the most essential python-nitrate features are:
The main motivation was to hide unnecessary implementation details
wherever possible so that using the API is as concise as possible.
-Initialize or create an object:
+Scripts importing python-nitrate can make use of several useful
+helper functions including info() for logging to stderr, listed()
+which converts list into nice human readable form, color() for
+coloring and of course log.{debug,info,warn,error} for logging.
+
+
+EXAMPLES
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Initialize or create an object::
testcase = TestCase(1234)
testrun = TestRun(testplan=<plan>, summary=<summary>)
-Default iterators provided for all container objects:
+Default iterators provided for all container objects::
- for case in TestRun(1234):
+ for case in TestRun(1234)::
if case.automated:
case.status = Status("RUNNING")
-Linking case to a plan is as simple as adding an item to a set:
+Linking case to a plan is as simple as adding an item to a set::
testplan.testcases.add(testcase)
However, it's still possible to use the low-level driver when a
-specific features is not implemented yet or not efficient enough:
+specific features is not implemented yet or not efficient enough::
testcasehash = Nitrate()._server.TestCase.get(46490)
-Scripts importing python-nitrate can make use of several useful
-helper functions including info() for logging to stderr, listed()
-which converts list into nice human readable form, color() for
-coloring and of course log.{debug,info,warn,error} for logging.
-
-
-Examples
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
For a quick start you can get some inspiration in the examples
directory. The 'matrix.py' script demonstrates how to easily
display a matrix view of the test run results for a specific test
@@ -57,14 +69,7 @@ plan. The 'create.py' script gives a broader overview covering
object creation, attribute setting, adjusting logs and caching.
-Documentation
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-For a short introduction see the manual page. For more detailed
-and most up-to-date description of all available nitrate module
-features see Python online documentation using 'pydoc nitrate'.
-
-
-Test Suite
+TEST SUITE
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The high-level interface has an integrated test suite, which can
be easily run against a stage server instance. For this a couple
@@ -73,21 +78,50 @@ so that we can check valid results. For detailed information about
what data has to be prepared see the module documentation.
-Links
+LINKS
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-python-nitrate project page:
-https://fedorahosted.org/python-nitrate/
+Project page:
+http://psss.fedorapeople.org/python-nitrate/
Nitrate test case management system:
https://fedorahosted.org/nitrate/
-Enjoy!
+SEE ALSO
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+For more detailed and most up-to-date description of all available
+nitrate module features see the Python online documentation::
+
+ pydoc nitrate
+ pydoc nitrate.xmlrpc
+
+
+AUTHORS
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+High-level Python module:
+Petr Šplíchal <psplicha@redhat.com>,
+Zbyšek Mráz <zmraz@redhat.com>.
+
+Low-level XMLRPC driver:
+Airald Hapairai,
+David Malcolm <dmalcolm@redhat.com>,
+Will Woods <wwoods@redhat.com>,
+Bill Peck <bpeck@redhat.com>,
+Chenxiong Qi <cqi@redhat.com>,
+Tang Chaobin <ctang@redhat.com>,
+Yuguang Wang <yuwang@redhat.com>
+and Xuqing Kuang <xuqingkuang@gmail.com>.
+
Hope, the library will save you time and bring some joy when
writing scripts interacting with the Nitrate server. Looking
forward to your feedback, comments, suggestions and patches ;-)
-Petr Šplíchal
-<psplicha@redhat.com>
+COPYRIGHT
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Copyright (c) 2012 Red Hat, Inc. All rights reserved.
+
+This library is free software; you can redistribute it and/or
+modify it under the terms of the GNU Lesser General Public
+License as published by the Free Software Foundation; either
+version 2.1 of the License, or (at your option) any later version.
diff --git a/documentation/nitrate.man b/documentation/nitrate.man
deleted file mode 100644
index ade1542..0000000
--- a/documentation/nitrate.man
+++ /dev/null
@@ -1,84 +0,0 @@
-.\" Man page generated from reStructeredText.
-.
-.TH NITRATE 1 "" "" ""
-.SH NAME
-nitrate \- Python API for the Nitrate test case management system
-.
-.nr rst2man-indent-level 0
-.
-.de1 rstReportMargin
-\\$1 \\n[an-margin]
-level \\n[rst2man-indent-level]
-level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
--
-\\n[rst2man-indent0]
-\\n[rst2man-indent1]
-\\n[rst2man-indent2]
-..
-.de1 INDENT
-.\" .rstReportMargin pre:
-. RS \\$1
-. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
-. nr rst2man-indent-level +1
-.\" .rstReportMargin post:
-..
-.de UNINDENT
-. RE
-.\" indent \\n[an-margin]
-.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
-.nr rst2man-indent-level -1
-.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
-.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
-..
-.SH SYNOPSIS
-.sp
-nitrate
-.SH DESCRIPTION
-.sp
-python\-nitrate provides a high\-level Python interface to the
-Nitrate test case management system. The package also provides
-standalone script \(aqnitrate\(aq which allows easy experimenting with
-the interface directly from the Python interpreter by importing
-all available objects and enabling the readline support. In short,
-after setting your configuration you can directly manipulate all
-nitrate objects, for example:
-.sp
-.nf
-.ft C
-$ nitrate
->>> for case in TestRun(123):
-\&... print case
-.ft P
-.fi
-.SH CONFIGURATION
-.sp
-To be able to contact the Nitrate server a minimal user config
-file ~/.nitrate has to be provided in the user home directory:
-.sp
-.nf
-.ft C
-[nitrate]
-url = https://nitrate.server/xmlrpc/
-.ft P
-.fi
-.SH SEE ALSO
-.sp
-For more detailed and most up\-to\-date description of all available
-nitrate module features see Python online documentation:
-.sp
-.nf
-.ft C
-pydoc nitrate
-.ft P
-.fi
-.SH AUTHORS
-.sp
-Written by Petr Splichal <\fI\%psplicha@redhat.com\fP>. The Python xmlrpc
-driver is based on the work of Airald Hapairai, David Malcolm
-<\fI\%dmalcolm@redhat.com\fP>, Will Woods <\fI\%wwoods@redhat.com\fP> and Bill Peck
-<\fI\%bpeck@redhat.com\fP> and was enhanced by Chenxiong Qi <\fI\%cqi@redhat.com\fP>,
-Tang Chaobin <\fI\%ctang@redhat.com\fP>, Yuguang Wang <\fI\%yuwang@redhat.com\fP> and
-Xuqing Kuang <\fI\%xuqingkuang@gmail.com\fP>.
-.\" Generated by docutils manpage writer.
-.\"
-.
diff --git a/documentation/nitrate.rst b/documentation/nitrate.rst
index f32a1a6..a0e6671 100644
--- a/documentation/nitrate.rst
+++ b/documentation/nitrate.rst
@@ -1,31 +1,32 @@
-
-==================================================================
- nitrate
-==================================================================
+===============
+ nitrate
+===============
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- Python API for the Nitrate test case management system
+ Command line interpreter for the Nitrate Python API
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
:Manual section: 1
+:Manual group: User Commands
+:Date: February 2012
SYNOPSIS
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
nitrate
DESCRIPTION
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
python-nitrate provides a high-level Python interface to the
Nitrate test case management system. The package also provides
standalone script 'nitrate' which allows easy experimenting with
the interface directly from the Python interpreter by importing
-all available objects and enabling the readline support. In short,
-after setting your configuration you can directly manipulate all
-nitrate objects, for example::
+all available objects and enabling the readline support.
+
+In short, after setting your configuration you can easily
+manipulate all Nitrate objects from the command line, for
+example::
$ nitrate
>>> for case in TestRun(123):
@@ -34,7 +35,6 @@ nitrate objects, for example::
CONFIGURATION
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
To be able to contact the Nitrate server a minimal user config
file ~/.nitrate has to be provided in the user home directory::
@@ -44,19 +44,9 @@ file ~/.nitrate has to be provided in the user home directory::
SEE ALSO
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+python-nitrate
-For more detailed and most up-to-date description of all available
-nitrate module features see Python online documentation::
-
- pydoc nitrate
-
-AUTHORS
+AUTHOR
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Written by Petr Splichal <psplicha@redhat.com>. The Python xmlrpc
-driver is based on the work of Airald Hapairai, David Malcolm
-<dmalcolm@redhat.com>, Will Woods <wwoods@redhat.com> and Bill Peck
-<bpeck@redhat.com> and was enhanced by Chenxiong Qi <cqi@redhat.com>,
-Tang Chaobin <ctang@redhat.com>, Yuguang Wang <yuwang@redhat.com> and
-Xuqing Kuang <xuqingkuang@gmail.com>.
+Petr Šplíchal <psplicha@redhat.com>