Update README.md

tools/essence-feature-usage-stats/.env

@@ -2,7 +2,7 @@ ESSENCE_DIR=/home/mayday/Coding/VIP/EssenceCatalog
 CONJURE_DIR=/home/mayday/Coding/VIP/conjure
 ESSENCE_EXAMPLES_REPO=https://github.com/conjure-cp/EssenceCatalog.git
 CONJURE_REPO=https://github.com/conjure-cp/conjure
-OUTPUT_PATH=./table.html
+OUTPUT_PATH=./web/static/table.html
 KEYWORD_BLOCKLIST="mInfo,finds,givens,enumGivens,enumLettings,lettings,
  unnameds,strategyQ,Auto,Interactive,strategyA,trailCompact,
  nameGenState,nbExtraGivens,representations,representationsTree,

tools/essence-feature-usage-stats/README.md

@@ -11,35 +11,49 @@ It does the following:
 The purpose of this is to make it easier to find Essence examples to test specific Essence language features, which should be useful over the course of rewriting the conjure tool stack in Rust
 
 
-## Usage
-
-> This is heavily WIP and I am planning to make this more usable in the future.
-> Eventually, this will be a Flask web server to host the web page, a better frontend (to make it searchable, sortable, etc), and the page will auto-update on changes to the relevant Essence example repos
+## Building
 
-For now, though:
+The static HTML page is generated by running the main.py script.
 
-- Put paths to conjure directory and Essence file directory in .env
-- Run the main.py file
-- See the generated HTML file
+The page is placed in the ./web/static directory by default. 
+This can be configured using the OUTPUT_PATH environment variable, but paths to the script and stylesheet
+inside the index.html template will need to be updated. 
+The GitHub action also assumes that path and won't work if it's changed.
 
+It is deployed using GitHub Pages: see https://conjure-cp.github.io/conjure-oxide/tools/essence-feature-usage-stats
 
-## ToDo
-
-- [x] Get basic stats in JSON format
-- [x] Get basic stats as HTML table
-- [ ] Table sorting
-- [x] Code refactoring
-- [ ] Documentation
-- [ ] Show/Hide table rows/columns
-- [ ] Web server for hosting the HTML page
-- 🏗️ GitHub Actions integration
-- [x] Extra stats, e.g. file line count
-- [ ] Sorting using these stats
 
+## Usage
 
-------------------------------------------
+- Essence example files are taken from the [EssenceCatalog](https://github.com/conjure-cp/EssenceCatalog) repo. This can be changed using an environment variable - see bellow.
+- Table headers show Essence keywords
+- Table row headers show paths to Essence example files and the size of the files (in lines of code)
+- Table cells show how often a given keyword is used in a given file
+- Cells are colour coded. Red means a keyword is NOT used in this file, orange means it's used less than average, green means it's used more
+- Columns are sortable. Click on table header cells to sort rows by how often this keyword is used in each file.
+- Sorting by the first column (the one with file names) will sort by file size
+- The section above the table is a list of Essence keywords, sorted by their total usage accross files
+- The "Show" checkboxes in this section show/hide table columns
+- The "Any", "Require", "Exclude" radio button allows you to filter the table by specific keywords:
+ - "Require" means that only files that have one or more usage of this keyword will be shown
+ - "Exclude" means that only files that don't use this keyword will be shown
+ - "Any" means that files will be shown regardless of whether they use this feature
+ - These can be combined to search for exactly the right files to test specific Essence features
+
+## Configuration
+
+- ESSENCE_DIR - local directory to store essence files
+- CONJURE_DIR - local directory to store conjure binaries
+- ESSENCE_EXAMPLES_REPO - repo to download Essence examples from
+- CONJURE_REPO - repo to download the latest release of conjure from
+- OUTPUT_PATH - path to save the generated HTML page. Be careful with changing this (see above).
+- KEYWORD_BLOCKLIST - comma-separated list of Essence keywords to ignore
+
+---
+
+## Authors
 
 - Georgii Skorokhod and Hannah Zheng, 2023
 - University of St Andrews
 - Developed as part of a Vertically Integrated Project by Ozgur Akgun et al
-- (See [main repos](https://github.com/conjure-cp))
+- (See [main repo](https://github.com/conjure-cp))

tools/essence-feature-usage-stats/web/templates/table.html

@@ -13,7 +13,7 @@
  <tbody>
  {% for file in files %}
  <tr hide_filters="0">
- <td n_lines="{{ file.n_lines }}">{{ file.get_str_path(depth=2) }}</td>
+ <td n_lines="{{ file.n_lines }}">{{ file.get_str_path(depth=2) }} <i>({{ file.n_lines }} LoC)</i></td>
  {% for essence_keyword in keywords %}
  {% set n_uses = file.get_uses(essence_keyword.name) %}
  {% set colour = essence_keyword.get_colour(n_uses).as_hex() %}