Technical Documentation - ryangurn/regtools GitHub Wiki
Technical Documentation
TODO:
- Refer to the 'Technical Documentation' section found at the bottom of https://classes.cs.uoregon.edu/20W/cis422/Project_Evaluation.html for the expectations for this document.
- Refer to previous feedback from Prof. Hornof as well. (jg: I will post my old docs on Discord with the feedback)
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
- Download and unzip the program archive.
- Open a terminal window.
- Type in and execute
cd <program-directory>
to change the working directory into the folder that was unzipped. - Type in and execute
python3 Main.py
. - 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