exor

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

Install | User Docs | Crate Docs | Reference | Contributing | License | 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 in rust.

Usage

Install exor with cargo.

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

exor --config op-reth.yml

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

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, a templating engine inspired by Jinja2 and the Django language template.

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 if no relevant issue already exists.

Attribution

exor is a ground-up rewrite of @protolambda's forkdiff site.

License

This project is licensed under the MIT License. Free and open-source, forever.