Changeset 4362


Ignore:
Timestamp:
26 Jun 2009, 11:16:51 (16 years ago)
Author:
uli
Message:

Make course documentation Sphinx-aware.

File:
1 edited

Legend:

Unmodified
Added
Removed

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

    r4267 r4362  
    1 Courses
    2 *******
     1:mod:`waeup.university.course` -- Courses
     2*****************************************
     3
     4.. module:: waeup.university.course
     5
     6Components that represent courses.
    37
    48:Test-Layer: unit
    59
     10Because this module makes use of components registered with the Zope
     11Component Architecture (ZCA), we first have to grok the `waeup`
     12package if we want to deploy it. This happens automatically in
     13real-world use:
     14
     15    >>> import grok
     16    >>> grok.testing.grok('waeup')
     17
     18Content Classes (models and containers)
     19=======================================
     20
     21:class:`Course`
     22---------------
     23
     24.. class:: Course([code=u'NA'[, title=u'Unnamed Course'[, level=None[, credits=0[, passmark=40[, semester=1]]]]]])
     25
     26   Create a course instance with the given parameters.
     27
     28   .. attribute:: grok.implements(ICourse)
     29
     30   All parameters are optional:
     31
     32     >>> from waeup.university.course import Course
     33     >>> mycourse = Course()
     34     >>> mycourse
     35     <waeup.university.course.Course object at 0x...>
     36
     37   Course instances have the attributes required by the
     38   :class:`waeup.interfaces.ICourse` interface:
     39
     40     >>> from waeup.interfaces import ICourse
     41     >>> ICourse.providedBy(mycourse)
     42     True
     43
     44     >>> from zope.interface.verify import verifyObject
     45     >>> verifyObject(ICourse, mycourse)
     46     True
     47
     48   .. attribute:: title
     49
     50      Each course has a title:
     51
     52        >>> mycourse.title
     53        u'Unnamed Course'
     54
     55   .. attribute:: code
     56
     57      Each course holds a code, which might be a shortcut or
     58      abbreviation of the real course name. By default the code is
     59      ``NA`` (=not assigned).
     60
     61      This value has to be unique if used in a :class:`Department`
     62      instance as it serves as a key:
     63
     64        >>> mycourse.code
     65        u'NA'
     66
     67   .. attribute:: passmark
     68
     69      Each course holdes a passmark, which is ``40`` by default:
     70
     71        >>> mycourse.passmark
     72        40
     73
     74   .. attribute:: semester
     75
     76      Each course holds a semester attribute which is ``1`` by
     77      default:
     78
     79        >>> mycourse.semester
     80        1
     81
     82   .. attribute:: credits
     83
     84      Each course holds the number of credits that can be
     85      earned. Default is ``0``.
     86
     87        >>> mycourse.credits
     88        0
     89
     90   .. attribute:: level
     91
     92      Courses can have a level. This attribute is not required and the
     93      default value is ``None``:
     94
     95        >>> mycourse.level is None
     96        True
     97
     98
     99Utilities
     100=========
     101
     102:class:`CourseFactory`
     103---------------------------
     104
     105.. class:: CourseFactory()
     106
     107   .. attribute:: grok.name(u'waeup.Course')
     108
     109   .. attribute:: grok.implements(IFactory)
     110
     111   A named utility to deliver new instances of :class:`Course`
     112   without the need to import the implementation before:
     113
     114     >>> from zope.component import createObject
     115     >>> mycourse = createObject(u'waeup.Course')
     116     >>> mycourse
     117     <waeup.university.course.Course object at 0x...>
     118
     119   The factory complies with the specifications from the
     120   :class:`IFactory` insterface:
     121
     122     >>> from zope.interface.verify import verifyClass
     123     >>> from zope.component.interfaces import IFactory
     124     >>> from waeup.university.course import CourseFactory
     125     >>> verifyClass(IFactory, CourseFactory)
     126     True
     127
     128   This means also, that we can get the interfaces of the created
     129   object from the factory:
     130
     131     >>> course_factory = CourseFactory()
     132     >>> course_factory.getInterfaces()
     133     <implementedBy waeup.university.course.Course>
     134
     135Examples
     136========
     137
    6138Creating courses
    7 ================
     139----------------
    8140
    9 We can create courses:
     141The simplest way to create a :class:`Course` instance is to import the
     142class and calling the constructor:
    10143
    11144    >>> from waeup.university.course import Course
    … …  
    15148
    16149Another way to create courses is by asking for a factory called
    17 ``waeup.Course``. Before we can do this, we have to grok the `waeup`
    18 package. This happens automatically in real-world use:
    19 
    20     >>> import grok
    21     >>> grok.testing.grok('waeup')
    22 
    23 Now we can create a factory without importing a class:
     150``waeup.Course``. This way we can create a factory without importing a
     151class:
    24152
    25153    >>> from zope.component import createObject
    … …  
    28156    <waeup.university.course.Course object at 0x...>
    29157
    30 Course attributes
    31 ==================
    32 
    33 Courses have the attributes required by the `ICourse` interface:
    34 
    35     >>> from waeup.interfaces import ICourse
    36     >>> ICourse.providedBy(mycourse)
    37     True
    38 
    39     >>> from zope.interface.verify import verifyObject
    40     >>> verifyObject(ICourse, mycourse)
    41     True
    42 
    43 Each of the following attributes except ``level`` is mandatory.
    44 
    45 `title`
    46 -------
    47 
    48 Each course has a title:
    49 
    50     >>> mycourse.title
    51     u'Unnamed Course'
    52 
    53 `code`
    54 ------
    55 
    56 Each course holds a code, which might be a shortcut or abbreviation
    57 of the real course name. By default the code is ``NA`` (=not assigned):
    58 
    59     >>> mycourse.code
    60     u'NA'
    61 
    62 `passmark`
    63 ----------
    64 
    65 Each course holdes a passmark, which is 40 by default:
    66 
    67     >>> mycourse.passmark
    68     40
    69 
    70 `semester`
    71 ----------
    72 
    73 Each course holds a semester attribute which is 1 by default:
    74 
    75     >>> mycourse.semester
    76     1
    77 
    78 `credits`
    79 ---------
    80 
    81 Each course holds the number of credits that can be earned. Default is
    82 0.
    83 
    84     >>> mycourse.credits
    85     0
    86 
    87 `level`
    88 -------
    89 
    90 Courses can have a level. This attribute is not required and the
    91 default value is ``None``:
    92 
    93     >>> mycourse.level is None
    94     True
Note: See TracChangeset for help on using the changeset viewer.