# exor

[![Build Status]][actions]
[![License]][mit-license]
[![Docs]][Docs-rs]
[![Latest Version]][crates.io]
[![rustc 1.31+]][Rust 1.31]

[Build Status]: https://img.shields.io/github/actions/workflow/status/refcell/exor/ci.yml?branch=main
[actions]: https://github.com/refcell/exor/actions?query=branch%3Amain
[Latest Version]: https://img.shields.io/crates/v/exor.svg
[crates.io]: https://crates.io/crates/exor
[rustc 1.31+]: https://img.shields.io/badge/rustc_1.31+-lightgray.svg
[Rust 1.31]: https://blog.rust-lang.org/2018/12/06/Rust-1.31-and-rust-2018.html
[License]: https://img.shields.io/badge/license-MIT-7795AF.svg
[mit-license]: https://github.com/refcell/exor/blob/main/LICENSE.md
[Docs-rs]: https://docs.rs/exor/
[Docs]: https://img.shields.io/docsrs/exor.svg?color=319e8c&label=docs.rs


**Batteries included cli tool for generating git fork diff documentation websites via YAML configuration files.**
Exor is in https://github.com/refcell/exor/labels/beta

![](./etc/banner.png)

**[Install](#usage)**
| [User Docs](#what-is-exor)
| [Crate Docs][crates.io]
| [Reference][Docs-rs]
| [Contributing](#contributing)
| [License](#license)
| [Attribution](#attribution)

## What is exor?

`exor` is a batteries included cli tool that can
generate websites with verbose documentation for
git fork diffs using YAML configuration files. The
project is rewrite of [forkdiff][forkdiff] in rust.

## Usage

Install `exor` with cargo.

```bash
cargo install exor
```

// TODO: Inline image of a documentation website

To generate the above git fork diff documentation
website, you would use the following YAML configuration
file and pass it into `exor` using the `--config` (or `-c`
for short) like so

```bash
exor --config op-reth.yml
```

Below is the `op-reth.yml` config file used above.

```yaml
title: "op-reth"
logo: "./etc/logo.png"
footer: |
  [Fork-diff](https://github.com/protolambda/forkdiff) overview of [op-reth](https://github.com/anton-rs/op-reth), a fork of [reth](https://github.com/paradigmxyz/reth) and execution-engine of the [OP Stack](https://github.com/ethereum-optimism/optimism).
base:
  name: paradigmxyz/reth
  url: https://github.com/paradigmxyz/reth
  ref: refs/heads/main
fork:
  name: anton-rs/op-reth
  url: https://github.com/anton-rs/op-reth
  ref: refs/heads/clabby/op-reth
def:
    title: "op-reth"
    description: |
      This is an overview of the changes in [op-reth](https://github.com/anton-rs/op-reth), a fork of [reth](https://github.com/paradigmxyz/reth), part of the [OP Stack](https://github.com/ethereum-optimism/optimism).
      <br />
      <br />
      Similar minimal-diff forks of Ethereum Execution Clients for the [OP Stack](https://github.com/ethereum-optimism/optimism) include:
        <br />
        - [op-erigon](https://github.com/testinprod-io/op-erigon) built by [testinprod-io](https://github.com/testinprod-io).
        <br />
        - [op-geth](https://github.com/ethereum-optimism/op-geth) built by [optimism](https://github.com/ethereum-optimism/optimism).
    globs:
      - "hello/world/greeter.go"  # list files of which the patches should be included
      - "hello/util/*"  # use file globs to include multiple files
      - "hello/util/*[!_test].go"  # you can ignore things with globs too
    sub:
      - title: "Consensus Crate"
        description: "Documents op-reth changes to the consensus crate."
        globs:
          - "crates/consensus/*"
          - "crates/consensus/auto-seal/src/lib.rs"
        sub:
          - title: "Beacon Head Updates"
            description: "Allows the beacon consensus engine to update the head."
            globs:
              - "crates/consensus/beacon/*"
              - "crates/consensus/beacon/src/engine/*"
          - title: "Consensus Validation Changes"
            description: "Validates consensus headers behind the optimism feature flag only when the optimism chain spec option is truthy."
            globs:
              - "crates/consensus/common/*"
              - "crates/consensus/common/src/*"
      - title: "Miscellaneous"
        description: "Automated or otherwise unimportant file changes."
        globs:
          - "Cargo.lock"
          # The EF Test Cargo.toml is picked up on a strange carriage return diff I believe
          - "testing/ef-tests/Cargo.toml"
ignore:
  - "*.sum"
```

Under the hood, `exor` uses [tera][tera], a templating engine
inspired by [Jinja2][jinja] and the [Django language template][dj].

[tera]: https://github.com/Keats/tera
[jinja]: http://jinja.pocoo.org/
[dj]: https://docs.djangoproject.com/en/3.1/topics/templates/

## Contributing

All contributions are welcome! Experimentation is highly encouraged
and new issues are welcome.

## Troubleshooting & Bug Reports

Please check existing issues for similar bugs or
[open an issue](https://github.com/refcell/exor/issues/new)
if no relevant issue already exists.

## Attribution

`exor` is a ground-up rewrite of [@protolambda][proto]'s
[forkdiff][forkdiff] site.

[proto]: https://github.com/protolambda
[forkdiff]: https://github.com/protolambda/forkdiff

## License

This project is licensed under the [MIT License](LICENSE.md).
Free and open-source, forever.