Metadata-Version: 2.3
Name: website_diff
Version: 0.0.1
Classifier: Programming Language :: Rust
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Requires-Dist: click
Requires-Dist: loguru
Requires-Dist: beautifulsoup4
Requires-Dist: pillow
Requires-Dist: numpy
Requires-Dist: vl-convert-python
Requires-Dist: maturin
License-File: LICENSE
Summary: A simple tool for producing navigable, highlighted diffs of rendered HTML websites
Author-email: Trevor Campbell <trevor.d.campbell@gmail.com>
Requires-Python: >=3.9
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM

# Website Diff

`website_diff` is a utility that compares two HTML websites, and outputs a diff *as a third HTML website*.
The diff site has insertion/deletion highlighting, automatic scroll-to-next and scroll-to-previous key bindings,
image diffing, and highlighting of links pointing to diffed pages.

![demo](https://github.com/trevorcampbell/website_diff/assets/59274601/369fd570-cb37-4910-8918-ad77bf0cb9ea)

## Why would I use `website_diff`?
This tool is primarily meant to help see/find differences in websites that are automatically generated from some source
documents (e.g. documentation pages, Jupyterbooks, etc) that may not be obvious from source diffs produced by GitHub.
This is particularly useful when the source documents run code whose output may silently change, even though the source
files remain constant.

## Installation
Ensure Rust and Cargo are installed. Instructions can be found [here](https://www.rust-lang.org/tools/install).

```
pip install --upgrade pip
pip install website_diff
```

## Usage
`website_diff` takes as an input two folders each containing an `index.html` file, as well as the name of a third folder to be created
that will contain the diffed website.
```
website_diff --old path/to/old/site/ --new path/to/new/site/ --diff path/where/diff/site/will/be/created
```
If `website_diff` runs successfully, the diff website will be available at
```
path/where/diff/site/will/be/created/index.html
```

To access the command line interface help documentation, run
```
website_diff --help
```

There are several examples that can demonstrate the kinds of differences that website_diff will detect.

To run website_diff on those examples, simply run the bash script `run_tests.sh` found within the website_diff repo.

`run_tests.sh` pulls the examples from a separate repo called `website_diff_examples`. 

The folder `website_diff_examples/examples` contains several folders each representing a different example e.g. lines of text changed, image added, page added, etc. 

In each of those folders, there will be an `old` and `prerendered_old` folder for the old website and old website with pre-rendered figures, `new` and `prerendered_new` for the new website and new website with pre-rendered figures, and lastly `diff` for the diffed version of the website with an `index.html` file that shows everything that has changed between the old and new versions of the website.

## Navigation

To view diffs, open `index.html` in the output folder (specified by the --diff option). 

Text diffs are highlighted in green if text was inserted, red if text was deleted. Any links that point to a page containing diffs will have yellow text.

Any new image elements will have a green border and are highlighted in green, deleted image elements will have a red border and are highlighted in red.

If an old image source file was replaced with a new image file, the image on the diff'd page will be outlined in yellow and any differences in the image will be highlighted in red. 

### Keyboard controls

When first opening a page with diffs, the browser will scroll to the first diff on the page.

To scroll to the next off-page diff, press the **n** key.

To scroll to the previous off-page diff, press **Shift+n** or **N**. 

