kubik369 / votr

Next generation AIS frontend

Votr

Votr is an alternative frontend providing easier access to AIS2, the academic information system used at many universities in Slovakia. If you are a student of Comenius University, you can try Votr at https://votr.uniba.sk. If you need help, write to us at [e-mail]. If you're interested in the development of Votr, read on.

AIS2 doesn't have an official API, so Votr primarily uses web scraping. The AIS2 servers think they're talking to a real user with a real web browser pressing buttons and navigating the endless popup windows that form AIS2's user interface. But it is in fact Votr, sending simulated button presses and parsing AIS2's mangled tag soup.

Votr's code base consists of three layers that build on each other. Aisikl, the lowest layer, does the actual communication by sending HTTP requests with fake user actions and parsing the responses from WebUI (the framework AIS2 is based on). Fladgejt contains the business logic for various AIS2 tasks and knows where to find which buttons and tables. And Votrfront is the web app that Votr's users interact with.

Running Votr

1. Install Python 3.4+ and virtualenv. On recent Ubuntu or Debian, use:

   sudo apt install virtualenv
   

2. Install node.js and npm. (Some Linux distributions bundle them together in one package.) Check the version: npm 1 and 2 are too old. npm 3 and 4 are probably OK. npm 5+ is ideal, but most Linux distributions don't have it yet (including current Ubuntu and Debian). In that case, you can either:

   • Install npm 3 despite its age and hope for the best. E.g. on Ubuntu: sudo apt install nodejs-legacy npm.
   • Use the unofficial up to date repositories from https://nodejs.org/en/download/package-manager/, and install nodejs (not nodejs-legacy and npm).

3. Create a virtualenv directory. A virtualenv is an isolated environment that contains Python libraries, so that you don't have to install them system-wide, and each project can use different versions without conflicts.

   virtualenv -p python3 venv
   

4. Activate the virtualenv. (Basically, this just adds venv/bin to your current shell's $PATH. Instead, you could just use venv/bin/python instead of python, venv/bin/pip instead of pip, etc.)

   source venv/bin/activate
   

5. Install the latest version of pip (earlier versions don't support wheels), and then use it to install Python dependencies.

   pip install -U pip
   pip install -r requirements.txt
   

6. Start Votr. Remember to activate the virtualenv first if you haven't done it yet in this terminal.

   ./console.py serve --debug
   

Contributing to Votr

If you'd like to help improve Votr, please get in touch! E-mail us at [e-mail] and we'll help you with anything you need -- whether it's choosing a task to work on, understanding Votr's code, implementing your changes, or sending a pull request on GitHub.

Developer documentation

Some documentation is on the wiki: https://github.com/fmfi-svt/votr/wiki

Some documentation is in docstrings in the source code and rendered with Sphinx: http://svt.fmph.uniba.sk/~tomi/votrdoc/

Building documentation:

pip install sphinx sphinx-rtd-theme
make -C docs html