Changeset 13168 for main/waeup.kofa/trunk/docs/source/userdocs/hostels.rst

Timestamp:

14 Jul 2015, 20:17:10 (9 years ago)

Author:

Henrik Bettermann

Message:

More docs.

File:

• main/waeup.kofa/trunk/docs/source/userdocs/hostels.rst (modified) (1 diff)

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

@@ -21 +21 @@
 ==========
 
+`IHostelsContainer`
+-------------------
+
+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 `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
    :pyobject: IHostelsContainer
 
+`IHostel`
+---------
+
+The hostels container contains the various `Hostel` objects. Hostels are  buildings with blocks, floors rooms and beds. When adding a hostel, the form page is requesting the hostel's name. The `hostel_id` is derived from the name by applying :code:`lower().replace(' ','-').replace('_','-')` to it. As usual, the id will be omitted in manage forms and can thus not be changed after hostel creation.
+
+The add and manage form pages let us define the 'dimensions' of the hostel and and configure blocks with their assignment to either female or male students. And they are requesting the number of floors per block as well as the number of rooms per floor. All blocks have the same number of floors with a fixed number of rooms and a fixed number of beds per room. If beds or even entire rooms do not exist on a floor, these beds must be later marked reserved, so that they are skipped during the automatic allocation process, see below.
+
+.. note::
+
+  Blocks for either female or male students? Does Kofa's hostel management accommodate girls and boys strictly separately? No, it doesn't. Blocks are not necessarily real buildings. They can be used as virtual subunits. If the entire hostel has only one block, then yes, either only female or only male students can be hosted in such a hostel. If two blocks are configured (one for male and one for female students), beds of the same room can be assigned to either the female or the male block, which means - even though very uncommon - girls and boys would be accommodated in the same room.
+
 .. literalinclude:: ../../../src/waeup/kofa/hostels/interfaces.py
    :pyobject: IHostel
 
+Beds can be dedicated to pre-study students, fresh students (`entry_session` and the hostels container's `accommodation_session` correspond), final-year students (`current_level` and the certificate's `end_level` correspond, or is even higher) and returning students (non-fresh and non-final-year students). Or they can be made bookable for all students (beds without category). The latter bed type can be configured but is not being used in the base package by :py:meth:`getAccommodationDetails<waeup.kofa.students.utils.StudentsUtils.getAccommodationDetails>`, the method which determines the appropriate bed type of the student.
+
+Usually, not every student can be accommodated in every hostel. Faculties are sometimes far apart and do manage their own student hostels. These hostels require a 'special handling' in :py:meth:`getAccommodationDetails<waeup.kofa.students.utils.StudentsUtils.getAccommodationDetails>`. The special handling code must be set on the add and manage form pages of hostels.
+
+The interface defines also two schema invariants (invariant-decorated methods). These methods validate one or more depending schema fields. In our case, the methods take care that blocks and beds are not assigned twice.
+
+All the parameters above define the construction rules for beds when filling the hostel with beds, which is done by the `updateBeds` method described further below.
+
+`IBed`
+------
+
 .. literalinclude:: ../../../src/waeup/kofa/hostels/interfaces.py
    :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, 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, 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).