Technical Documentation - ryangurn/regtools GitHub Wiki

Technical Documentation

TODO:

Authors Key
Ryan Gurnick rg
Joseph Goh jg
Samuel Lundquist sl
Mason Sayyadi ms
Owen McEvoy om

1. Technical Documentation Revision History

Date Author Description
03/06/2020 jg created initial document with placeholder sections
03/06/2020 jg added starter information to sections 3 and 4 as well as general guidelines for filling out the remaining information
03/07/2020 jg all mentions of regTools changed to Registration Tools
03/07/2020 jg added rudimentary install and execute instructions

2. Installation and Execution Instructions

  1. Download and unzip the program archive.
  2. Open a terminal window.
  3. Type in and execute cd <program-directory> to change the working directory into the folder that was unzipped.
  4. Type in and execute python3 Main.py.
  5. The program is now running. The terminal window may be minimized but must not be closed before exiting the program.

3. Software Dependencies

The system, Registration Tools, is built entirely upon Python and packages from the Python Standard Library.

The most significant components from the Python Standard Library that have been use are listed below:

  • tkinter: The entirety of the system's graphical user interface is built using tkinter, Python's built-in interface to the Tk GUI toolkit.

  • sqlite3: The system's Class Data and Status Store is built and managed using SQLite and is therefore accessed and manipulated using the sqlite3 package.

  • json: Most information in the Class Data and Status Store is structured in JSON (JavaScript Object Notation) using the json package.

  • html.parser: The Class Web Scraper module uses html.parser to automatically parse the course information displayed at http://classes.uoregon.edu/ for processing into the Class Data and Status Store.

  • TODO: Add additional Python Standard Library package links and brief descriptions as necessary.

4. Required Versions of Components

TODO: Specify target OS versions and fill in any additional version constraints.

The system is designed to run on Python 3.7 and 3.8 as well as the Python Standard Library packages that that comes bundled with those versions. Compatibility with other versions of Python, older or newer, is not guaranteed nor to be expected.

The system is designed to run specifically on macOS [target-OS-version]. Compatibility with different operating systems or macOS versions is not guaranteed nor to be expected either.

5. Relationship Between Files

TODO:

  • Each file relevant to the system is to be listed, preferably in sections grouped by the software module their primary role relates to. (This includes non-code files such as database or image files.)
  • Each file should be followed by a brief description of their role and relationship to other files and components.

6. Breakdown of Files

TODO:

  • Each code and database or configuration file should be listed in the same groups as in the previous section.

  • Each code file should have subsections for classes, methods, and global variables as appropriate.

  • For database/config files, it would be nice to have even a brief description of how the file is structured and to be accessed, but if it feels redundant and already explained by another file's description, it should be fine to just refer to that file.

  • jg: _From my experience in the last project, I'm thinking that we needn't give in-depth explanations of each small code section here. More specifically, if something is much more effectively explainable using inline comments within source code files, it would be unnecessary and redundant to put that information here.

    At the very least, we should give an exhaustive list of classes, methods, and global variables, but the description for each can be brief.

    That being said, for the tkinter GUI, it's probably easier to not list everything on here, so use best judgement and write what seems useful/feasible