[WIP] Documentation

docs/.gitignore

@@ -1 +1,2 @@
 build
+_site

docs/404.md

@@ -0,0 +1,4 @@
+---
+---
+
+404 Page not found.

docs/Doxyfile

@@ -1,7 +1,7 @@
 PROJECT_NAME = "Timetabler"
 OUTPUT_DIRECTORY = build
-INPUT = .. ../README.md
-EXCLUDE = ../tests ../dependencies ../snap ../parts ../prime ../stage ../build ../docs
+INPUT = ..
+EXCLUDE = ../tests ../dependencies ../build ../docs ../parts ../prime ../snap ../stage ../examples
 RECURSIVE = YES
 QUIET = YES
 GENERATE_HTML = YES

docs/Gemfile

@@ -0,0 +1,2 @@
+source 'https://rubygems.org'
+gem 'github-pages', group: :jekyll_plugins

docs/Gemfile.lock

@@ -0,0 +1,248 @@
+GEM
+  remote: https://rubygems.org/
+  specs:
+    activesupport (4.2.10)
+      i18n (~> 0.7)
+      minitest (~> 5.1)
+      thread_safe (~> 0.3, >= 0.3.4)
+      tzinfo (~> 1.1)
+    addressable (2.5.2)
+      public_suffix (>= 2.0.2, < 4.0)
+    coffee-script (2.4.1)
+      coffee-script-source
+      execjs
+    coffee-script-source (1.11.1)
+    colorator (1.1.0)
+    commonmarker (0.17.13)
+      ruby-enum (~> 0.5)
+    concurrent-ruby (1.0.5)
+    dnsruby (1.61.2)
+      addressable (~> 2.5)
+    em-websocket (0.5.1)
+      eventmachine (>= 0.12.9)
+      http_parser.rb (~> 0.6.0)
+    ethon (0.11.0)
+      ffi (>= 1.3.0)
+    eventmachine (1.2.7)
+    execjs (2.7.0)
+    faraday (0.15.3)
+      multipart-post (>= 1.2, < 3)
+    ffi (1.9.25)
+    forwardable-extended (2.6.0)
+    gemoji (3.0.0)
+    github-pages (192)
+      activesupport (= 4.2.10)
+      github-pages-health-check (= 1.8.1)
+      jekyll (= 3.7.4)
+      jekyll-avatar (= 0.6.0)
+      jekyll-coffeescript (= 1.1.1)
+      jekyll-commonmark-ghpages (= 0.1.5)
+      jekyll-default-layout (= 0.1.4)
+      jekyll-feed (= 0.10.0)
+      jekyll-gist (= 1.5.0)
+      jekyll-github-metadata (= 2.9.4)
+      jekyll-mentions (= 1.4.1)
+      jekyll-optional-front-matter (= 0.3.0)
+      jekyll-paginate (= 1.1.0)
+      jekyll-readme-index (= 0.2.0)
+      jekyll-redirect-from (= 0.14.0)
+      jekyll-relative-links (= 0.5.3)
+      jekyll-remote-theme (= 0.3.1)
+      jekyll-sass-converter (= 1.5.2)
+      jekyll-seo-tag (= 2.5.0)
+      jekyll-sitemap (= 1.2.0)
+      jekyll-swiss (= 0.4.0)
+      jekyll-theme-architect (= 0.1.1)
+      jekyll-theme-cayman (= 0.1.1)
+      jekyll-theme-dinky (= 0.1.1)
+      jekyll-theme-hacker (= 0.1.1)
+      jekyll-theme-leap-day (= 0.1.1)
+      jekyll-theme-merlot (= 0.1.1)
+      jekyll-theme-midnight (= 0.1.1)
+      jekyll-theme-minimal (= 0.1.1)
+      jekyll-theme-modernist (= 0.1.1)
+      jekyll-theme-primer (= 0.5.3)
+      jekyll-theme-slate (= 0.1.1)
+      jekyll-theme-tactile (= 0.1.1)
+      jekyll-theme-time-machine (= 0.1.1)
+      jekyll-titles-from-headings (= 0.5.1)
+      jemoji (= 0.10.1)
+      kramdown (= 1.17.0)
+      liquid (= 4.0.0)
+      listen (= 3.1.5)
+      mercenary (~> 0.3)
+      minima (= 2.5.0)
+      nokogiri (>= 1.8.2, < 2.0)
+      rouge (= 2.2.1)
+      terminal-table (~> 1.4)
+    github-pages-health-check (1.8.1)
+      addressable (~> 2.3)
+      dnsruby (~> 1.60)
+      octokit (~> 4.0)
+      public_suffix (~> 2.0)
+      typhoeus (~> 1.3)
+    html-pipeline (2.8.4)
+      activesupport (>= 2)
+      nokogiri (>= 1.4)
+    http_parser.rb (0.6.0)
+    i18n (0.9.5)
+      concurrent-ruby (~> 1.0)
+    jekyll (3.7.4)
+      addressable (~> 2.4)
+      colorator (~> 1.0)
+      em-websocket (~> 0.5)
+      i18n (~> 0.7)
+      jekyll-sass-converter (~> 1.0)
+      jekyll-watch (~> 2.0)
+      kramdown (~> 1.14)
+      liquid (~> 4.0)
+      mercenary (~> 0.3.3)
+      pathutil (~> 0.9)
+      rouge (>= 1.7, < 4)
+      safe_yaml (~> 1.0)
+    jekyll-avatar (0.6.0)
+      jekyll (~> 3.0)
+    jekyll-coffeescript (1.1.1)
+      coffee-script (~> 2.2)
+      coffee-script-source (~> 1.11.1)
+    jekyll-commonmark (1.2.0)
+      commonmarker (~> 0.14)
+      jekyll (>= 3.0, < 4.0)
+    jekyll-commonmark-ghpages (0.1.5)
+      commonmarker (~> 0.17.6)
+      jekyll-commonmark (~> 1)
+      rouge (~> 2)
+    jekyll-default-layout (0.1.4)
+      jekyll (~> 3.0)
+    jekyll-feed (0.10.0)
+      jekyll (~> 3.3)
+    jekyll-gist (1.5.0)
+      octokit (~> 4.2)
+    jekyll-github-metadata (2.9.4)
+      jekyll (~> 3.1)
+      octokit (~> 4.0, != 4.4.0)
+    jekyll-mentions (1.4.1)
+      html-pipeline (~> 2.3)
+      jekyll (~> 3.0)
+    jekyll-optional-front-matter (0.3.0)
+      jekyll (~> 3.0)
+    jekyll-paginate (1.1.0)
+    jekyll-readme-index (0.2.0)
+      jekyll (~> 3.0)
+    jekyll-redirect-from (0.14.0)
+      jekyll (~> 3.3)
+    jekyll-relative-links (0.5.3)
+      jekyll (~> 3.3)
+    jekyll-remote-theme (0.3.1)
+      jekyll (~> 3.5)
+      rubyzip (>= 1.2.1, < 3.0)
+    jekyll-sass-converter (1.5.2)
+      sass (~> 3.4)
+    jekyll-seo-tag (2.5.0)
+      jekyll (~> 3.3)
+    jekyll-sitemap (1.2.0)
+      jekyll (~> 3.3)
+    jekyll-swiss (0.4.0)
+    jekyll-theme-architect (0.1.1)
+      jekyll (~> 3.5)
+      jekyll-seo-tag (~> 2.0)
+    jekyll-theme-cayman (0.1.1)
+      jekyll (~> 3.5)
+      jekyll-seo-tag (~> 2.0)
+    jekyll-theme-dinky (0.1.1)
+      jekyll (~> 3.5)
+      jekyll-seo-tag (~> 2.0)
+    jekyll-theme-hacker (0.1.1)
+      jekyll (~> 3.5)
+      jekyll-seo-tag (~> 2.0)
+    jekyll-theme-leap-day (0.1.1)
+      jekyll (~> 3.5)
+      jekyll-seo-tag (~> 2.0)
+    jekyll-theme-merlot (0.1.1)
+      jekyll (~> 3.5)
+      jekyll-seo-tag (~> 2.0)
+    jekyll-theme-midnight (0.1.1)
+      jekyll (~> 3.5)
+      jekyll-seo-tag (~> 2.0)
+    jekyll-theme-minimal (0.1.1)
+      jekyll (~> 3.5)
+      jekyll-seo-tag (~> 2.0)
+    jekyll-theme-modernist (0.1.1)
+      jekyll (~> 3.5)
+      jekyll-seo-tag (~> 2.0)
+    jekyll-theme-primer (0.5.3)
+      jekyll (~> 3.5)
+      jekyll-github-metadata (~> 2.9)
+      jekyll-seo-tag (~> 2.0)
+    jekyll-theme-slate (0.1.1)
+      jekyll (~> 3.5)
+      jekyll-seo-tag (~> 2.0)
+    jekyll-theme-tactile (0.1.1)
+      jekyll (~> 3.5)
+      jekyll-seo-tag (~> 2.0)
+    jekyll-theme-time-machine (0.1.1)
+      jekyll (~> 3.5)
+      jekyll-seo-tag (~> 2.0)
+    jekyll-titles-from-headings (0.5.1)
+      jekyll (~> 3.3)
+    jekyll-watch (2.1.2)
+      listen (~> 3.0)
+    jemoji (0.10.1)
+      gemoji (~> 3.0)
+      html-pipeline (~> 2.2)
+      jekyll (~> 3.0)
+    kramdown (1.17.0)
+    liquid (4.0.0)
+    listen (3.1.5)
+      rb-fsevent (~> 0.9, >= 0.9.4)
+      rb-inotify (~> 0.9, >= 0.9.7)
+      ruby_dep (~> 1.2)
+    mercenary (0.3.6)
+    mini_portile2 (2.3.0)
+    minima (2.5.0)
+      jekyll (~> 3.5)
+      jekyll-feed (~> 0.9)
+      jekyll-seo-tag (~> 2.1)
+    minitest (5.11.3)
+    multipart-post (2.0.0)
+    nokogiri (1.8.5)
+      mini_portile2 (~> 2.3.0)
+    octokit (4.13.0)
+      sawyer (~> 0.8.0, >= 0.5.3)
+    pathutil (0.16.1)
+      forwardable-extended (~> 2.6)
+    public_suffix (2.0.5)
+    rb-fsevent (0.10.3)
+    rb-inotify (0.9.10)
+      ffi (>= 0.5.0, < 2)
+    rouge (2.2.1)
+    ruby-enum (0.7.2)
+      i18n
+    ruby_dep (1.5.0)
+    rubyzip (1.2.2)
+    safe_yaml (1.0.4)
+    sass (3.6.0)
+      sass-listen (~> 4.0.0)
+    sass-listen (4.0.0)
+      rb-fsevent (~> 0.9, >= 0.9.4)
+      rb-inotify (~> 0.9, >= 0.9.7)
+    sawyer (0.8.1)
+      addressable (>= 2.3.5, < 2.6)
+      faraday (~> 0.8, < 1.0)
+    terminal-table (1.8.0)
+      unicode-display_width (~> 1.1, >= 1.1.1)
+    thread_safe (0.3.6)
+    typhoeus (1.3.0)
+      ethon (>= 0.9.0)
+    tzinfo (1.2.5)
+      thread_safe (~> 0.1)
+    unicode-display_width (1.4.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  github-pages
+
+BUNDLED WITH
+   1.16.4

docs/README.md

@@ -0,0 +1,25 @@
+# Generate docs site locally
+
+1. Install Ruby and Bundler.
+    ```bash
+    sudo apt install -y libssl-dev libreadline-dev curl
+    curl -fsSL https://github.com/rbenv/rbenv-installer/raw/master/bin/rbenv-installer | bash
+    echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.bashrc
+    echo 'eval "$(rbenv init -)"' >> ~/.bashrc
+    curl -fsSL https://github.com/rbenv/rbenv-installer/raw/master/bin/rbenv-doctor | bash
+    rbenv install 2.4.4
+    rbenv global 2.4.4
+    gem install bundler
+    ```
+2. In the docs folder, run the following to install dependencies.
+    ```bash
+    bundle install
+    ```
+3. Run the following command to generate the site.
+    ```bash
+    bundle exec jekyll serve
+    ```
+    Now the site will be hosted locally at `https://localhost:4000/Timetabler/`.
+
+---
+This theme is a fork of [Cayman theme from GitHub pages](https://github.com/pages-themes/cayman/).

docs/_config.yml

@@ -1 +1,8 @@
-theme: jekyll-theme-cayman
+title: Timetabler
+baseurl: /Timetabler
+collections:
+  docs:
+    output: true
+
+plugins:
+  - jekyll-mentions

docs/_docs/constraints.md

@@ -0,0 +1,58 @@
+---
+layout: default
+title: Default constraints
+---
+
+# Default constraints implemented in the Timetabler
+
+This page describes the default constraints implemented in the Timetabler. Broadly, there are three types of constraints:
+
+1. User Assignment Constraints
+1. Field Value Assignment Constraints
+1. Scheduling Constraints
+
+## User Assignment Constraints
+These constraints specify the extent to which the assignment of field values by the user must be respected. For example, if the user specifies that course A must have instructor B, then the weight of this constraint specifies whether the solver can change the instructor if needed, and if so, at what priority, or if must not change the field even if it means that creating a timetable is no longer possible. Weights are specified per field type.
+
+The rules for specifying the weights are the same - a zero weight implies that the solver can freely change the field value, a negative weight implies that the solver must not change the value under any circumstance, and a positive weight provides how much importance the solver must give to this constraint relative to other constraints. These weights can be modified as usual in the fields file.
+
+By default, the weights for these are 1, except for the fields IsMinor, Program, and Instructor, for which the weights are -1. This is under the assumption that the fact whether a course is minor, the programs for which a course is applicable, and the instructor of the course may not be flexible.
+
+If any field in the input is left empty for a given course, the effective weight for that field pertaining to that course becomes zero.
+
+## Field Value Assignment Constraints
+These constraints specify the extent to which the solver must try to obtain a field value for a given field type, which is consistent with other constraints provided. For example, for the field type Instructor, this specifies the importance the solver must give to ensure that every course is assigned an instructor. Weights are specified per field type. This applied to all field types except Program, because assigning a program to a course is not an essential aspect, whereas every course generally needs an instructor, classroom, etc.
+
+Once again, a a zero weight implies that the solver need not assign a field value to the particular field type, a negative weight implies that the solver must assign a value under any circumstance, and a positive weight provides how much importance the solver must give to this constraint relative to other constraints. These weights can be modified in the fields file. By default, the weights for these are 1.
+
+## Scheduling Constraints
+These constraints specify the rules to follow to ensure feasible scheduling. They include constraints such as the constraint that an instructor or a classroom cannot have two courses scheduled at the same time. They also include soft clauses, such as to try to place a core course in a morning slot.
+
+The weights can be set using the same rules as already specified. By default, the weights are -1, as violating most of these constraints would not make practical sense. The exception is for soft clauses, which are - a core course should be in morning time, an elective course should be in non-morning time, the weights for which are 1. Any slot for which each time slot element begins before 1pm is considered to be a morning slot.
+
+The following are the list of scheduling constraints implemented:
+
+1. **instructorSingleCourseAtATime** \\
+An Instructor can have only one course in a given segment and slot.
+1. **classroomSingleCourseAtATime** \\
+A Classroom can have only one course in a given segment and slot.
+1. **programSingleCoreCourseAtATime** \\
+No program can have two core courses with an intersecting schedule.
+1. **minorInMinorTime** \\
+A minor course must be given a minor slot and vice-versa. A slot can be specified to be a minor slot in the field input.
+1. **exactlyOneSlotPerCourse** \\
+A course must be given exactly one Slot. A slot is a set of time units in the week given a name, and is specified in the field input.
+1. **exactlyOneInstructorPerCourse** \\
+A course must be given exactly one Instructor.
+1. **exactlyOneSegmentPerCourse** \\
+A course must be given exactly one Segment. A "Segment" refers to a Segment object, which consists of a start and an end segment. For example, a course can be in the 14 segment, but it cannot be in both the 14 and 36 segments (in this case, it would actually then be in the 16 segment).
+1. **exactlyOneIsMinorPerCourse** \\
+A course must be given exactly one IsMinor value. This means that a course can either be a minor course or not, but not both.
+1. **exactlyOneClassroomPerCourse** \\
+A course must be given exactly one Classroom.
+1. **coreInMorningTime** \\
+A core course must be scheduled in a morning slot. This is by default a soft clause with weight 1. A morning slot is a slot in which all time units in the week have the start time before 1pm.
+1. **electiveInNonMorningTime** \\
+An elective course must be scheduled in a non morning slot. This is by default a soft clause with weight 1. A non-morning slot is any slot which is not a morning slot. In particular, it may have some time units in the week that are in the morning.
+1. **programAtMostOneOfCoreOrElective** \\
+A course can be applicable to a program as a core or elective, not both.