Documentation (man page and coverage overview)

3 files changed, 239 insertions, 0 deletions

diff --git a/documentation/coverage.txt b/documentation/coverage.txt
new file mode 100644
index 0000000..8b11e4b
--- /dev/null
+++ b/documentation/coverage.txt
@@ -0,0 +1,93 @@
+
+This is an overview of the object/attribute coverage. Useful to
+compare the actual names used for different xmlrpc calls.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ Test Plan Properties
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+FIELD             CREATE                    GET                         UPDATE
+id                ---                       plan_id                     ---
+author            ---                       author_id                   ---
+name              name*                     name                        name
+parent            parent                    parent_id                   parent
+product           product*                  product_id                  product
+product.version   default_product_version*  default_product_version     default_product_version
+type              type*                     type_id                     type
+---               text*                     TestPlan.get_text           TestPlan.store_text
+---               is_active                 is_active                   is_active
+---               ---                       create_date                 ---
+---               ---                       extra_link                  ---
+---               ---                       ---                         env_group
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ Test Run Properties
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+FIELD         CREATE              GET                 UPDATE
+id            ---                 run_id              ---
+testplan      plan*               plan_id             plan?
+build         build*              build_id            build
+manager       manager*            manager_id          manager
+summary       summary*            summary             summary
+product       product*            ---                 product
+---           product_version*    product_version     product_version
+tester        default_tester      default_tester_id   default_tester
+---           plan_text_version                       plan_text_version
+time          estimated_time      estimated_time      estimated_time
+notes         notes               notes               notes
+status        status              ---                 status
+caseruns      case                ---                 ---
+tags          tag                 ---                 ---
+---           ---                 environment_id      ---
+---           ---                 plan_text_version   ---
+---           ---                 start_date          ---
+---           ---                 stop_date           ---
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ Test Case Properties
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+FIELD         CREATE              GET                 UPDATE
+id            ---                 case_id             ---
+arguments     arguments           arguments           arguments
+author        ---                 author_id           ---
+automated     is_automated        is_automated        is_automated
+bugs          bug                 ---                 ---
+category      category*           category_id         category
+components    component           ---                 ---
+notes         notes               notes               notes
+testplans     plan                ---                 ---
+priority      priority*           priority_id         priority
+---           product*            ---                 product
+script        script              script              script
+sortkey       sortkey             sortkey             sortkey
+status        case_status         case_status_id      case_status
+summary       summary*            summary             summary
+tags          tag                 ---                 ---
+tester        default_tester      default_tester_id   default_tester
+time          estimated_time      estimated_time      estimated_time
+---           is_automated_pro... is_automated_pro... is_automated_pro...
+---           requirement         requirement         requirement
+---           alias               alias               alias
+---           action              text.action         ---
+---           effect              text.effect         ---
+---           setup               text.setup          ---
+---           breakdown           text.breakdown      ---
+---           ---                 create_date         ---
+---           ---                 reviewer_id         ---
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ Case Run Properties
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+FIELD         CREATE              GET                 UPDATE
+id            ---                 case_run_id         ---
+assignee      assignee            assignee_id         assignee
+build         build*              build_id            build
+notes         notes               notes               notes
+sortkey       sortkey             sortkey             sortkey
+status        case_run_status     case_run_status_id  case_run_status
+testcase      case*               case_id             ---
+testrun       run*                run_id              ---
+---           case_text_version   case_text_version   ---
diff --git a/documentation/nitrate.man b/documentation/nitrate.man
new file mode 100644
index 0000000..ade1542
--- /dev/null
+++ b/documentation/nitrate.man
@@ -0,0 +1,84 @@
+.\" 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
new file mode 100644
index 0000000..f32a1a6
--- /dev/null
+++ b/documentation/nitrate.rst
@@ -0,0 +1,62 @@
+
+==================================================================
+ nitrate
+==================================================================
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ Python API for the Nitrate test case management system
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+:Manual section: 1
+
+
+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::
+
+    $ nitrate
+    >>> for case in TestRun(123):
+    ...     print case
+
+
+CONFIGURATION
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To be able to contact the Nitrate server a minimal user config
+file ~/.nitrate has to be provided in the user home directory::
+
+    [nitrate]
+    url = https://nitrate.server/xmlrpc/
+
+
+SEE ALSO
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+For more detailed and most up-to-date description of all available
+nitrate module features see Python online documentation::
+
+    pydoc nitrate
+
+
+AUTHORS
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+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>.