Refactor testing

.github/workflows/pythonpackage.yml

@@ -16,7 +16,7 @@ jobs:
       matrix:
         # these will be out of date again eventually, add the latest versions
         # and remove the unsupported ones
-        python-version: ['3.6', '3.7', '3.8', '3.9', '3.10']
+        python-version: ['3.7', '3.8', '3.9', '3.10', '3.11']
     name: Python ${{ matrix.python-version }}
     steps:
     - uses: actions/checkout@v3

LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 Evan New-Schmidt
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,40 +1,40 @@
 # focstest
+
 _(you can skip to [Getting Started](#getting-started))_
 
+_If you're looking to update this for a new semester, see [Development](#development)._
+
 So, you're in Olin's FoCS (Foundations of Computer Science) course and you've
 started to fill out the functions for this week's homework assignment. You're
 looking at the homework document and you find a bunch of blocks of example
 outputs like these:
 ```
-# expt 1 0;;
-- : int = 1
-# expt 1 3;;
-- : int = 1
-# expt 2 3;;
-- : int = 8
+# splits [];;
+- : ('a list * 'a list) list = [([], [])]
+# splits [1];;
+- : (int list * int list) list = [([], [1]); ([1], [])]
+# splits [1; 2; 3; 4];;
+- : (int list * int list) list =
+[([], [1; 2; 3; 4]); ([1], [2; 3; 4]); ([1; 2], [3; 4]); ([1; 2; 3], [4]);
+ ([1; 2; 3; 4], [])]
 ```
-Sure, you could type those in one-by-one into the `ocaml` (or
+
+Sure, you could copy those in one-by-one into the `ocaml` (or
 [`utop`](https://github.com/ocaml-community/utop)) interpreter and check them
-yourself, but this is a computer science course! There's got to be a slightly
-faster way that may or may not have taken more development time to create than
-it saved...
+yourself with your tired eyes, but this is a computer science course! There's
+got to be a slightly faster way that may or may not have taken more development
+time to create than it saved...
 
-Introducing:
-```
-  __                _            _
- / _| ___   ___ ___| |_ ___  ___| |_
-| |_ / _ \ / __/ __| __/ _ \/ __| __|
-|  _| (_) | (__\__ \ ||  __/\__ \ |_
-|_|  \___/ \___|___/\__\___||___/\__|
-```
-Finally, the doctest-ish ocaml program that you've always wanted!
+Introducing focstest: the doctest-ish ocaml program that you've always wanted!
 
 Replace those tedious seconds of typing with a simple
 `focstest homework1.ml` and watch your productivity soar!
 
 `focstest` is packed with many useful features, including:
 - colors!
-- 
+- test selection!
+- error parsing!
+- cache invalidation!
 
 Just read these (mostly real) testimonials:
 
@@ -64,35 +64,50 @@ Just read these (mostly real) testimonials:
 
 ### Prerequisites
 
-You'll need Python 3.5+ and `pip`.
+You'll need Python 3.7+ and `pip`.
 
-The `ocaml` interpreter needs to be installed and on your PATH (you can run it
+The `ocaml` interpreter needs to be installed and on your PATH (i.e. you can run it
 from a terminal).
 
 ### Installation
 
 #### Pip
 
-The recommended way to install `focstest` is through `pip`, which will install the
-necessary package requirements and add `focstest` to your terminal. You can do
-this by cloning the source repository to somewhere on your machine and running
-`pip install`:
-
+The recommended way to install and upgrade `focstest` is through `pip`,
+which will install the necessary package requirements and add the `focstest`
+command to your terminal. _(Note that depending on your system, you may
+need to run `pip3` or `python3 -m pip` instead)_:
 ```shell
-git clone --branch=release https://github.com/olin/focstest.git  # clone a stable version
-pip install focstest/
+pip3 install git+https://github.com/olin/focstest.git
 ```
 
 You should now be able to run `focstest --help` and see the
 [usage message below](#usage).
 
+#### Pip (local)
+
+You can also install it by cloning the source repository to somewhere on
+your machine and running `pip install`
+
+```shell
+git clone https://github.com/olin/focstest.git
+pip install focstest/
+```
+
+To update to the latest version, pull from the remote and install again:
+```shell
+cd focstest/
+git pull
+pip install .
+```
+
 #### Manual
 
-Alternatively, you can run the `focstest.py` script directly after installing
-the necessary requirements:
+Alternatively, you can download and run the `focstest.py` script directly
+after installing the necessary requirements:
 
-The python packages `BeautifulSoup`, `requests`, and `termcolor` are required.
-Install them with `pip install bs4 requests termcolor`, or `pipenv install`.
+The python packages `beautifulsoup4`, `requests`, and `termcolor` are required.
+Install them with `pip install bs4 requests termcolor`.
 
 ### Usage
 
@@ -122,24 +137,23 @@ focstest homework2.ml --update-cache
 `focstest` uses a standard python-powered command-line interface. You can always
 ask it for help with `--help` or `-h`.
 
-```shell
+```
 $ focstest --help
-usage: focstest [-h] [--version] [--url URL] [-v] [-uc] [-u [N [N ...]] | -s
-                [N [N ...]]]
-                ocaml-file
+usage: focstest [-h] [--version] [--url URL | --from-html HTML_FILE] [-v] [--ignore-cache] [-u [N [N ...]] | -s [N [N ...]]] ocaml_file
 
 Run ocaml "doctests".
 
 positional arguments:
-  ocaml-file            the ocaml file to test against
+  ocaml_file            the ocaml file to test against
 
 optional arguments:
   -h, --help            show this help message and exit
   --version             show program's version number and exit
-  --url URL             a url to scrape tests from (usually automagically
-                        guessed from ocaml-file)
+  --url URL             a url to scrape tests from (usually automagically guessed from ocaml_file)
+  --from-html HTML_FILE
+                        a local html file to scrape tests from
   -v, --verbose         increase test output verbosity
-  -uc, --update-cache   update cached files
+  --ignore-cache        ignore cached files
   -u [N [N ...]], --use-suites [N [N ...]]
                         test suites to use exclusively, indexed from 1
   -s [N [N ...]], --skip-suites [N [N ...]]
@@ -177,15 +191,42 @@ $ focstest h1.ml -v
 
 Issues and Pull Requests are welcome!
 
-Run `pipenv install --dev` to install all of the dev packages.
+If you're interested in maintaining focstest, reach out to [any contributors](https://github.com/olin/focstest/graphs/contributors),
+or if that fails, a [member of the olin org](https://github.com/orgs/olin/people)
+for repo edit access.
 
-Run tests with `python -m unittest discover`.
-
-Want to use it while you hack on it? Install it with `pip install -e`.
+With the repository cloned to your machine:
+- Run `pipenv install --dev` to install all of the dev packages.
+- Run tests with `python -m unittest discover`.
+- Want to use it while you hack on it? Install it with `pip install -e`.
 
 You can set `focstest`'s logging level with the `LOG_LEVEL` environment variable.
-The possible values are all of python's usual logging levels, set it to `DEBUG`
-for more output.
+The possible values are all of python's [usual logging levels](https://docs.python.org/3/library/logging.html#levels), set it to `DEBUG` for more output.
+
 ```shell
 $ LOG_LEVEL=DEBUG focstest homework3.ml
 ```
+
+### Semesterly Updates
+
+With each new semester, the class url for homeworks changes and the webpage
+format may change.
+
+To update the url/filename formats, the relevant pieces to change are the function `infer_url` and the
+related variables for parsing filenames and creating the url: 
+`BASE_URL`, `OCAML_FILE_PATTERN`, `HTML_FILE_TEMPLATE`.
+
+To update the parsing of html files, the `get_blocks` function and `CODE_BLOCK_SELECTOR` variable is probably what you want. Ideally the selector can remain general enough to work with past and present pages.
+
+### Releases
+
+To release a new version of `focstest`:
+1. Make sure it really works and isn't broken (wait for the CI tests on github to pass).
+2. Create a new "tag" with `git tag v0.Y.Z`, where `v0.Y.Z` is the new version number. If you're not familiar with [semantic versioning](https://semver.org/), the TL;DR is:
+    - keeping the first number `0` communicates a certain amount of instability and under-development-ness, and is what all the cool projects do
+    - the second number `Y` is incremented when a breaking change is made, e.g. some cli flags have been changed or removed, or you feel like it (set `Z` back to 0 when you increment `Y`)
+    - the third number `Z` is incremented when there are only smaller changes or bugfixes
+3. Push the new tag to the github repo with `git push --tags`
+4. Create a new "release" by going to https://github.com/olin/focstest/releases/new>. Write some info about what's changed.
+
+That's it! The latest git tag is detected by pip automatically when installed.