Changeset 4326

Timestamp:

21 Jun 2009, 00:05:38 (15 years ago)

Author:

uli

Message:

Make dept docs sphinx-aware.

File:

• waeup/branches/ulif-rewrite/src/waeup/university/department.txt (modified) (2 diffs)

waeup/branches/ulif-rewrite/src/waeup/university/department.txt

@@ -1 @@
-Departments
-***********
+:mod:`waeup.university.department` -- Departments
+*************************************************
+
+.. module:: waeup.university.department
+
+Components that represent university departments.
 
 :Test-Layer: unit
 
-Creating departments
-====================
-
-Before we can create departments, we have to grok the `waeup`
+Before we can create departments, we have to grok the :mod:`waeup`
 package. This happens automatically in real-world use:
 
@@ -13 +14 @@
     >>> grok.testing.grok('waeup')
 
-We can create departments:
 
-    >>> from waeup.university.department import Department
-    >>> mydept = Department()
-    >>> mydept
-    <waeup.university.department.Department object at 0x...>
+Content Classes (models and containers)
+=======================================
 
-Another way to create departments is by asking for a factory called
-``waeup.Department``. This way we can create a department without
-importing a class:
 
-    >>> from zope.component import createObject
-    >>> mydept = createObject(u'waeup.Department')
-    >>> mydept
-    <waeup.university.department.Department object at 0x...>
+:class:`Department`
+-------------------
 
-Department attributes
-=====================
+.. class:: Department(title=u'Unnamed Department'[, title_prefix=u'department' [, code=u"NA"]])
 
-Departments have the attributes required by the `IDepartment` interface:
+   Create a representation of a university department:
 
-    >>> from waeup.interfaces import IDepartment
-    >>> IDepartment.providedBy(mydept)
-    True
+     >>> from waeup.university.department import Department
+     >>> mydept = Department()
+     >>> mydept
+     <waeup.university.department.Department object at 0x...>
 
-    >>> from zope.interface.verify import verifyObject
-    >>> verifyObject(IDepartment, mydept)
-    True
+   Another way to create :class:`Department` instances is by asking
+   for a factory called ``waeup.Department``. This way we can create a
+   department without importing a class:
 
-Each of the following attributes is mandatory.
+     >>> from zope.component import createObject
+     >>> mydept = createObject(u'waeup.Department')
+     >>> mydept
+     <waeup.university.department.Department object at 0x...>
 
-`title`
--------
+   :class:`Department` instances have the attributes required by the
+   `IDepartment` interface:
 
-Each department has a title:
+     >>> from waeup.interfaces import IDepartment
+     >>> IDepartment.providedBy(mydept)
+     True
 
-    >>> mydept.title
-    u'Unnamed Department'
+     >>> from zope.interface.verify import verifyObject
+     >>> verifyObject(IDepartment, mydept)
+     True
 
-`title_prefix`
---------------
 
-Each department has a title prefix, which specifies the kind of
-institution:
+   .. attribute:: title
 
-    >>> mydept.title_prefix
-    u'department'
+      (string) The title of a department.
 
-`code`
-------
+      Each department has a title:
 
-Each department holds a code, which might be a shortcut or
-abbreviation of the real department name. By default the code is ``NA``
-(=not assigned):
+        >>> mydept.title
+        u'Unnamed Department'
 
-    >>> mydept.code
-    u'NA'
 
-`courses`
----------
+   .. attribute:: title_prefix
 
-Each department has a courses container:
+      (string) The prefix of a department.
 
-    >>> mydept.courses
-    <waeup.university.coursecontainer.CourseContainer object at 0x...>
+      Each department has a title prefix, which specifies the kind of
+      institution:
+
+        >>> mydept.title_prefix
+        u'department'
+
+
+   .. attribute:: code
+
+      (string) An internally used unique code string.
+
+      Each department holds a code, which might be a shortcut or
+      abbreviation of the real department name. By default the code is
+      ``NA`` (=not assigned):
+
+        >>> mydept.code
+        u'NA'
+
+
+   .. attribute:: courses
+
+      (ICourseContainer instance) A container for courses.
+
+      Each department has a courses container:
+
+        >>> mydept.courses
+        <waeup.university.coursecontainer.CourseContainer object at 0x...>
+