Changeset 13171

Timestamp:

16 Jul 2015, 05:26:35 (9 years ago)

Author:

Henrik Bettermann

Message:

More docs.

File:

• main/waeup.kofa/trunk/docs/source/userdocs/hostels.rst (modified) (5 diffs)

main/waeup.kofa/trunk/docs/source/userdocs/hostels.rst

@@ -1 +1 @@
 .. _accommodation_section:
 
-Accommodation Section :sup:`in progress`
-****************************************
+Accommodation Section
+*********************
 
-The accommodation sections is a built-in hostel management system. African universities usually run their own student hostels which are built on their huge university campuses. They combine the booking of beds with the registration process. There are two major use cases. Students either have to book a bed space before they can continue with the registration, or they are only allowed to book, if they have reached a certain registration state. In the first case, the university requires students to stay on campus. They usually have enough beds for all of their students and need to fill up the hostels. In the second case, bed space is limited. Since accommodation is usually very reasonable and much safer on campus than on the free market outside, students prefer accommodation on campus. If bed allocation e.g. requires the payment of school fees, students are forced to pay in order to get the highly coveted hostel bed. 
+The accommodation sections is a built-in hostel management system. African universities usually run their own student hostels which are built on their huge university campuses. They combine the booking of beds with the registration process. There are two major use cases. Students either have to book a bed space before they can continue with the registration, or they are only allowed to book, if they have reached a certain registration state. In the first case, the university requires students to stay on campus. They usually have enough beds for all of their students and need to fill up the hostels. In the second case, bed space is limited. Since accommodation on campus is usually very reasonable and much safer than on the free market outside, students prefer to stay on campus. If bed allocation e.g. requires the payment of school fees, the university benefits from bed shortage, because students are forced to pay in order to get the highly coveted hostel bed.
 
-Technically speaking, the accommodation section is a container of type `HostelsContainer` with id ``hostels``, which is located in the `IUniversity` instance. It contains hostels (instances of `IHostel`) which again contain the beds (instances of `IBed`).
+From the database's point of view, the accommodation section is a container of type `HostelsContainer` with id ``hostels``, which is located in the `IUniversity` instance. It contains hostels (instances of `IHostel`) which again contain the beds (instances of `IBed`).
 
 The :ref:`treelike storage of objects <object_database>` in the
@@ -24 +24 @@
 -------------------
 
-The unique hostels container serves also as a configuration object. It defines for which academic session booking is enabled. The student's `current_session` must match the `accommodation_session`. It also defines the booking period and the registration workflow states for which booking is allowed, see :ref:`bed_tickets`. The only property attribute is `expired` which returns True if the current datetime is within the booking period.
+The unique hostels container serves also as a configuration object. It defines for which academic session booking is enabled. The student's `current_session` must match the `accommodation_session`. It also defines the booking period and the registration workflow states for which booking is allowed, see :ref:`bed_tickets`. The only property attribute is `expired` which returns ``True`` if the current datetime is within the booking period.
 
 .. literalinclude:: ../../../src/waeup/kofa/hostels/interfaces.py
@@ -57 +57 @@
    :pyobject: IBed
 
-The `bed_id` contains the 'coordinates' of the bed. It tells us precisely in which hostel, in which block, on which floor and in which room the bed can be found. The bed id is composed as follows: ``[hostel id]_[block letter]_[room number]_[bed letter]``. The room number contains the floor level: :code:`room_nr = floor*100 + room`. Example: ``hall-1_A_101_C`` means that the bed is located in Hostel 1, block A, 1st floor, room 101 (or 1) and labelled with 'C'.
+The `bed_id` contains the 'coordinates' of the bed. It tells us precisely in which hostel, in which block, on which floor and in which room the bed can be found. The bed id is composed as follows: ``[hostel id]_[block letter]_[room number]_[bed letter]``. The room number contains the floor level: :code:`room_nr = floor*100 + room`. Example: ``hall-1_A_101_C`` means that the bed is located in Hostel 1, Block A, 1st Floor, Room 101 (or 1) and labelled with 'C'.
 
 The `bed_type` attribute is similarly being constructed. It describes which kind of student can be allocated: ``[special handling code]_[sex]_[stage]``. Example: ``regular_female_re`` means that this bed can be booked by regular female returning students. Other stages are: ``fr`` (fresh), ``pr`` (pre-study), ``fi`` (final-year) and ``all`` (all students).
@@ -71 +71 @@
 -----------
 
-Hostels are empty after creation and configuration. They do not contain any bed. The hostel's :py:meth:`Hostel.updateBeds<waeup.kofa.hostels.hostel.Hostel.updateBeds>` method must be called to fill the hostel with beds according to the hostel's configuration parameters. This is done by the same-named action of the `HostelManageFormPage`. `Hostel.updateBeds` iterates over all block letters, floor levels, room numbers and bed letters set on the `HostelManageFormPage`, adds a bed and determines `bed_id`, `bed type` as well as the consecutive `bed_number` which are stored with the bed. This is quite straight.
+Hostels are empty after creation and configuration. They do not contain any bed. The hostel's :py:meth:`Hostel.updateBeds<waeup.kofa.hostels.hostel.Hostel.updateBeds>` method must be called to fill the hostel with beds according to the hostel's configuration parameters. This is done by the same-named action of the `HostelManageFormPage`. `Hostel.updateBeds` iterates over all block letters, floor levels, room numbers and bed letters, which haven been configured on the `HostelManageFormPage`. In each bed letter iteration loop a bed is added and the `bed_id`, `bed type` as well as the consecutive `bed_number` are determined and stored with the bed.
 
-As the method's name already promises, it does not only add beds to an empty hostel container, but also updates existing beds after re-configuration. It does this by removing all empty beds before the iteration starts. Occupied beds remain in hostel but get the bed number ``9999``. When iterating over the newly configured blocks, floors, rooms and bed letters, Kofa checks first, if the bed belongs to the remaining beds which could not be removed because they are occupied. If so, the bed type is adjusted and the bed number changed. The bed remains occupied by the same student, no matter if the student meets the newly configured conditions or not.
+As the method's name already promises, it does not only add beds to an empty hostel container, but also updates existing beds after re-configuration. It does this by removing all empty beds before the iteration starts. Occupied beds remain in the hostel but get the bed number ``9999``. When iterating over the newly configured blocks, floors, rooms and bed letters, Kofa checks first, if the bed belongs to the group of remaining beds, which could not be removed because they are occupied. If so, the bed type is adjusted and the bed number changed. The bed remains occupied by the same student, no matter if the student meets the newly configured conditions or not.
 
-It might happen that a room for male students is converted into a room for female students, but a male student still resides in this room. This has to be checked and the student has to be relocated manually, see :ref:`student_relocation`. Moreover, due to the reconfiguration of the hostel, an occupied bed may no longer exist or offered for booking. This is then indicated by the bed number ``9999``. Also these students must be relocated manually.
+It might happen that e.g. a room for male students is converted into a room for female students, but a male student still resides in this room. This has to be checked and the student has to be relocated manually, see :ref:`student_relocation`. Moreover, due to the reconfiguration of the hostel, an occupied bed may no longer exist or offered for booking. This is then indicated by the bed number ``9999``. Also these students must be relocated manually.
 
 
@@ -81 +81 @@
 -------------------
 
+Beds can be blocked by switching ther reservation status. The switch replaces the stage part of `bed_type` by ``_reserved``. Example: ``regular_female_re`` becomes ``regular_female_reserved``. Switching again, reverts this process.
+
+Reserved beds won't be allocated automatically. The beds remains empty during the hostel booking period. Students can only be allocated manually to reserved beds, which is done via the `BedManageFormPage`, see below.
+
 Release Beds
 ------------
+
+Releasing a bed does not simply mean clearing the `owner` attribute of the bed object. The student has to be notified that booking has been cancelled. This is done by replacing the `bed_coordinates` of the student's bed ticket. Instead of the coordinates, the student will read: ``-- booking cancelled on <datetime of cancellation> --``.
 
 Manage Bed
 ----------
 
+Not many things can be managed on this form page. As mentioned above, only the `owner` attribute can be changed by entering a student id. The id is being validated by a schema invariant. The manage form page cannot be accessed, if a student has aleady been allocated. Beds must be released first, before they can be allocated to other students.