Changeset 4313


Ignore:
Timestamp:
18 Jun 2009, 13:10:57 (15 years ago)
Author:
uli
Message:

Make certificate docs more sphinx-conform.

File:
1 edited

Legend:

Unmodified
Added
Removed

  • waeup/branches/ulif-rewrite/src/waeup/university/certificate.txt

    r4312 r4313  
    1 Certificates
    2 ************
     1:mod:`waeup.university.certificate` -- Certificates for WAeUP
     2*************************************************************
     3
     4Components that represent and manage certificates.
    35
    46:Test-Layer: unit
    5 
    6 Creating certificates
    7 =====================
    87
    98Because certificates make use of components registered with the Zope
    … …  
    1312    >>> import grok
    1413    >>> grok.testing.grok('waeup')
     14
     15
     16Content Classes (models and containers)
     17=======================================
     18
     19:class:`Certificate`
     20--------------------
     21
     22.. class:: Certificate([code=u'NA',[ title=u'Unnamed Certificate',[ category=None,[ study_mode=None,[ start_level=None,[ end_level=None,[ application_category=None,[ m_prefix=u'',[  max_pass = u'']]]]]]]]])
     23
     24   Create a certificate object with the given parameters.
     25
     26   .. attribute:: grok.implements(ICertificate)
     27
     28   All parameters are optional:
     29
     30     >>> from waeup.university.certificate import Certificate
     31     >>> mycertificate = Certificate()
     32
     33   Certificates have the attributes required by the `ICertificate` interface:
     34
     35     >>> from waeup.interfaces import ICertificate
     36     >>> ICertificate.providedBy(mycertificate)
     37     True
     38
     39     >>> from zope.interface.verify import verifyObject
     40     >>> verifyObject(ICertificate, mycertificate)
     41     True
     42
     43   .. attribute:: title
     44
     45      Each certificate has a title:
     46
     47        >>> mycertificate.title
     48        u'Unnamed Certificate'
     49
     50   .. attribute:: code
     51
     52      Each certificate holds a code, which might be a shortcut or
     53      abbreviation of the real certificate name. By default the code
     54      is ``NA`` (=not assigned):
     55
     56        >>> mycertificate.code
     57        u'NA'
     58
     59   .. attribute:: review_state
     60
     61      The review state can have one of the ``checking`` states defined
     62      in the WAeUP workflow. These are at least the states ``checked``
     63      and ``unchecked``. After a certificate is created, the review
     64      state is ``unchecked``:
     65
     66        >>> mycertificate.review_state
     67        'unchecked'
     68
     69      .. seealso::
     70         :meth:`Certificate.check` -- mark a certificate as ``checked``
     71
     72   .. attribute:: category
     73
     74      Each :class:`Certificate` instance has a category:
     75
     76        >>> print mycertificate.category
     77        None
     78
     79      .. XXX: This is not a proper description
     80
     81   .. attribute:: study_mode
     82
     83      Each :class:`Certificate` instance has a study mode:
     84
     85        >>> print mycertificate.study_mode
     86        None
     87
     88      .. XXX: This is not a proper description
     89
     90   .. attribute:: start_level
     91
     92      Each :class:`Certificate` instance has a start level:
     93
     94        >>> print mycertificate.start_level
     95        None
     96
     97      .. XXX: This is not a proper description
     98
     99   .. attribute:: end_level
     100
     101      Each :class:`Certificate` instance has a end level:
     102
     103        >>> print mycertificate.end_level
     104        None
     105
     106      .. XXX: This is not a proper description
     107   
     108
     109   .. attribute:: application_category
     110
     111      Each :class:`Certificate` instance has an application category:
     112
     113        >>> print mycertificate.application_category
     114        None
     115
     116      .. XXX: This is not a proper description
     117
     118   
     119   .. attribute:: m_prefix
     120
     121      Each :class:`Certificate` instance has an ``m_prefix``:
     122
     123        >>> print mycertificate.m_prefix
     124        None
     125
     126      .. XXX: This is not a proper description
     127
     128   
     129   .. attribute:: max_pass
     130
     131      Each :class:`Certificate` instance has a maximum number of passes:
     132
     133        >>> print mycertificate.max_pass
     134        None
     135
     136      .. XXX: This is not a proper description
     137
     138
     139   .. method:: check()
     140
     141      Mark a certificate instance's review state as ``checked``:
     142
     143        >>> mycertificate.review_state
     144        'unchecked'
     145
     146        >>> mycertificate.check()
     147        >>> mycertificate.review_state
     148        'checked'
     149
     150      We cannot uncheck a certificate:
     151
     152        >>> mycertificate.review_state = 'init'
     153        Traceback (most recent call last):
     154        ...
     155        InvalidTransitionError: Transition 'init' requires 'None'
     156          as source state (is: 'checked')
     157
     158
     159Utilities
     160=========
     161
     162:class:`CertificateFactory`
     163---------------------------
     164
     165.. class:: CertificateFactory()
     166
     167   .. attribute:: grok.name(u'waeup.Certificate')
     168
     169   .. attribute:: grok.implements(IFactory)
     170
     171   A named utility to deliver new instances of :class:`Certificate`
     172   without the need to import the implementation before:
     173
     174     >>> from zope.component import createObject
     175     >>> mycertificate = createObject(u'waeup.Certificate')
     176     >>> mycertificate
     177     <waeup.university.certificate.Certificate object at 0x...>
     178
     179Examples
     180========
     181
    15182
    16183We can create certificates:
    … …  
    30197    <waeup.university.certificate.Certificate object at 0x...>
    31198
    32 
    33 Certificate attributes
    34 ======================
    35 
    36 Certificates have the attributes required by the `ICertificate` interface:
    37 
    38     >>> from waeup.interfaces import ICertificate
    39     >>> ICertificate.providedBy(mycertificate)
    40     True
    41 
    42     >>> from zope.interface.verify import verifyObject
    43     >>> verifyObject(ICertificate, mycertificate)
    44     True
    45 
    46 Each of the following attributes is mandatory.
    47 
    48 `title`
    49 -------
    50 
    51 Each certificate has a title:
    52 
    53     >>> mycertificate.title
    54     u'Unnamed Certificate'
    55 
    56 `code`
    57 ------
    58 
    59 Each certificate holds a code, which might be a shortcut or abbreviation
    60 of the real certificate name. By default the code is ``NA`` (=not assigned):
    61 
    62     >>> mycertificate.code
    63     u'NA'
    64 
    65 `review_state`
    66 --------------
    67 
    68 The review state can have one of the ``checking`` states defined in
    69 the WAeUP workflow. These are at least the states ``checked`` and
    70 ``unchecked``. After a certificate is created, the review state is
    71 ``unchecked``:
    72 
    73     >>> mycertificate.review_state
    74     'unchecked'
    75 
    76 We can mark a certificate as checked:
    77 
    78     >>> mycertificate.check()
    79     >>> mycertificate.review_state
    80     'checked'
    81 
    82 We cannot uncheck a certificate:
    83 
    84     >>> mycertificate.review_state = 'init'
Note: See TracChangeset for help on using the changeset viewer.