Update README and rewrite contributing guidelines (#170)

* Update README and rewrite contributing guidelines

Update Python version badge in README.md from >= 3.6 to 3.12

Update usage examples in README.md to reflect updated API functions

Rewrite CONTRIBUTING.md to extensively document how to set up the
development and install required/recommended tooling

* Require black in contributing guidelines and fix typos

Update CONTRIBUTING.md to require contributors to use black rather than
simply encourage them to use it (see comments on PR #170). black will be
added as a pre-commit hook and GitHub workflow in a future PR.

* Add flake8 to contributing guidelines

* Fix typo in filepath

* Update Python version badge in README

* Replace Travis CI badge in README with GitHub Actions badge

Replace Travis CI badge with GitHub Actions badge since we no longer use
Travis and are now using GitHub actions

Delete .travis.yml config file for Travis since we no longer use Travis

CONTRIBUTING.md

@@ -1,4 +1,88 @@
 # Contributing Guidelines
-1. Please maintain proper commenting etiquette. Pretend that this is a work environment and that the comments are being reviewed by coworkers.
-1. Ensure that your changes compile/work before opening a PR.
-1. Follow style guidelines where applicable.
+
+To get started with contributing to the Pitt API, please read these guidelines in their entirety to set up your development environment and learn our tooling.
+
+## Initial Setup
+
+### Setting Up Your Virtual Environment
+
+The Pitt API uses [`pipenv`](https://pipenv.pypa.io/en/latest/) to manage its dependencies. As such, you should also use `pipenv` for your own Pitt API development rather than the more traditional `pip` and `venv`.
+
+To set up `pipenv`, first install the package using `pip`:
+```sh
+pip install --user pipenv
+```
+Now install `pipenv` to your local Pitt API git repo:
+```sh
+pipenv install
+```
+This will install all necessary dependencies listed in the [Pipfile](/Pipfile) and also set up your virtual environment.
+Start the virtual environment with
+```sh
+pipenv shell
+```
+and close it down with
+```sh
+exit
+```
+
+### Pre-Commit
+
+As a contributor, you should add [pre-commit](https://pre-commit.com/) to your development workflow in order to help us maintain a high-quality codebase.
+We've included several pre-commit hooks in [`.pre-commit-config.yaml`](/.pre-commit-config.yaml) that we consider to be essential for our purposes.
+
+pre-commit is installed automatically as a dependency when you set up your virtual environment with `pipenv`.
+To add pre-commit to your workflow, run
+```sh
+pre-commit install
+```
+From this point on, pre-commit should run whenever you make a commit.
+If it catches any errors (trailing whitespace, questionable code formatting, etc.), it'll try to fix them automatically or ask you to fix them if it can't.
+Make sure to fix all pre-commit errors before you commit.
+
+By default, pre-commit checks all modified files staged in your commit.
+If you want to run pre-commit on the entire repo, including files that you haven't modified, run
+```sh
+pre-commit run --all-files
+```
+
+## Contributing to the API
+
+To make a contribution to the Pitt API, simply open a PR from your local fork of the Pitt API repo.
+
+Naturally, you should ensure that contributions work and are of high quality before you make a PR.
+This includes making sure that your code compiles, passes all unit tests, and adhere to common style guidelines.
+
+### Unit Testing
+
+The Pitt API uses `pytest` for unit testing, and like pre-commit it's installed automatically when you set up `pipenv`.
+To run all unit tests, run
+```sh
+pytest --cov=pittapi tests/
+```
+
+### Code Quality
+
+To ensure consistent and readable code, we use the `flake8` linter and `black` formatter to help our code adhere to [PEP 8](https://peps.python.org/pep-0008/) style guidelines.
+`flake8` and `black` are also installed automatically when you set up `pipenv`, and they're also included in our pre-commit hooks.
+This means that if you have pre-commit set up correctly, pre-commit should run `flake8` and `black` automatically when you make a commit.
+
+However, if you wish to run the linter and formatter yourself, simply run these commands:
+```sh
+flake8 --max-line-length=127 .
+black --line-length=127 .
+```
+
+Apart from general code styling, you should also document and comment your code based on general best practices.
+This means that most if not all functions should have docstrings explaining their purpose, inputs, and outputs.
+This also means that comments should primarily be written to clarify code whose function isn't immediately obvious to the average reader.
+We may ask you to make changes to your documentation and comments during PR reviews.
+
+In terms of writing style, we expect you to write in a professional manner and follow proper commenting etiquette—pretend that this is a work environment and your comments are being reviewed by your manager and coworkers.
+
+### GitHub Workflows
+
+Note that we use automated GitHub workflows to check incoming PRs.
+For you as a contributor, this means that GitHub will run `flake8`, `black`, and `pytest` on your PR.
+For more information on the commands that we run as part of our workflows, please see our [workflows directory](/.github/workflows).
+Make sure your code pass all workflows before requesting a review.

README.md

@@ -1,79 +1,72 @@
 # Pitt API
 
-![Build Status](https://travis-ci.org/Pitt-CSC/PittAPI.svg?branch=master)
+![Build Status](https://img.shields.io/github/actions/workflow/status/pittcsc/PittAPI/tests-on-push.yml?branch=dev)
 ![License](https://img.shields.io/badge/license-GPLv2-blue.svg)
-![Python Version](https://img.shields.io/badge/python-%3E%3D%203.6-green.svg)
+![Python Version](https://img.shields.io/badge/python-%3E%3D%203.9-green.svg)
 
-Made by Ritwik Gupta at the University of Pittsburgh in an effort to get
-more open data from Pitt.
+The Pitt API is an unofficial Python API made by Ritwik Gupta at the University of Pittsburgh in an effort to get more open data from Pitt.
 
 ## Usage examples
 
 ```python
-from PittAPI import course, dining, lab, laundry, library, news, people, shuttle, textbook
+from pittapi import course, dining, lab, laundry, library, news, people, shuttle, textbook
 
 ### Courses
-# Will return a dictionary of all CS courses
+# Returns a dictionary of all courses for a given subject
 cs_subject = course.get_subject_courses(subject='CS')
 courses_dict = cs_subject.courses
 
-# Will return a list of sections of a course during a given term
+# Returns a list of sections of a course during a given term
 cs_course = course.get_course_details(term='2244', subject='CS', course='1501')
 section_list = cs_course.sections
 
 ### Textbook
-# Will return a list of dictionaries containing textbooks for a class
-# term number comes from pitt.verbacompare.com
+# Returns a list of dictionaries containing textbooks for a class
+# Term number comes from pitt.verbacompare.com
 small_dict = textbook.get_textbook(term="3150", department="CS", course="445", instructor="RAMIREZ")
 
 ### Library
-# Will return a dictionary containing results from query
+# Returns a dictionary containing results from query
 big_dict = library.get_documents(query="computer")
 
 ### News
-# Will return a list of dictionaries containing news from main news feed
+# Returns a list of dictionaries containing news from main news feed
 medium_dict = news.get_news()
 
 ### Laundry
-# Will return a dictionary with amount of washers and dryers
-# in use vs. total washers and dryers at building
+# Returns a dictionary with number of washers and dryers in use vs.
+# total washers and dryers in building
 small_dict = laundry.get_status_simple(building_name="TOWERS")
 
 ### Computer Lab
-# Will return a dictionary with status of the lab, and amount
-# of machines with a certain OS
+# Returns a dictionary with status of the lab and number of open machines
 small_dict = lab.get_status(lab_name="ALUMNI")
 
 ### Shuttle
-# Will return a list of dictionaries containing routes of shuttles
+# Returns a list of dictionaries containing routes of shuttles
 big_dict = shuttle.get_routes()
 
 ### People
-# Will return a list of people based on the query
+# Returns a list of people based on the query
 list_of_peeps = people.get_person(query="Smith")
 
 ### Dining
-# Will return a dictionary of dictionaries containing each dining location,
-# with its name, its open/closed status, and open times (if it exists)
+# Returns a dictionary of dictionaries containing each dining location with its
+# name and open/closed status
 medium_dict = dining.get_locations()
-medium_dict = dining.get_locations_by_status(status="open")
-medium_dict = dining.get_locations_by_status(status="closed")
-# Will return a single dictionary of a dining location,
-# with its name, its open/closed status, and open times (if it exists)
-one = dining.get_location_by_name("taco_bell-schenley_cafe")
-two = dining.get_location_by_name("cup_&_chaucer-hillman")
+# Returns a dictionary of a dining location with its hours for a given day
+hours = dining.get_location_hours("The Eatery", datetime.datetime(2024, 4, 12))
 ```
 
 ## Local Setup
 Install Python 3.12 and ``pipenv``.
 
 Run ``pipenv install`` and ``pipenv shell`` to create and setup the virtual environment.
 
-## Tests
+## Contributing
 
-Run tests with
-  ``pytest --cov=pittapi tests/``
+Read our [contributing guidelines](/CONTRIBUTING.md) to learn how to contribute to the Pitt API.
 
 ## License
 
-This project is licensed under the terms of the [GPLv2 license](/LICENSE)
+This project is licensed under the terms of the [GPLv2 license](/LICENSE).