Contributing¶

Development setup, checks, and documentation

If you have found an important feature missing from our tool, please suggest it by creating an issue. We also gratefully accept pull requests!

Development Setup¶

Install Python 3.11 or later.

Create and activate a virtual environment:

python3 -m venv venv/
source venv/bin/activate

Install the project dependencies:
```
pip install -e .[tests]
```

Install the spaCy model:

python -m spacy download en_core_web_sm

After having implemented a new feature, please check the code format, inspect common LINT errors, and run all unit tests with the following commands:

ruff check .                   # Code format and LINT
mypy .                         # Static typing
pytest .                       # Unit tests

Documentation¶

This documentation is built with MkDocs, the Material for MkDocs theme, and the mkdocs-webis plugin for the Webis style and citations. The sources are located in the docs/ directory and the configuration in mkdocs.yml.

Install the documentation dependencies:
```
pip install -e .[docs]
```
Preview the documentation locally (with live reload):
```
mkdocs serve
```
Build the documentation (as in CI, failing on warnings):
```
mkdocs build --strict
```

The documentation is deployed to GitHub Pages automatically on every release.

Citations¶

All references are stored in docs/references.bib and rendered by the mkdocs-webis plugin. To cite a reference in any page, use [@key] or [@key1; @key2] (with the BibTeX keys). The citations are rendered as author–year links, and each page that cites a reference automatically gets a "References" section at the bottom (including the BibTeX entries). Unknown keys fail the build.

When adding a reference, please copy its BibTeX entry from DBLP if the publication is indexed there.

Style¶

The mkdocs-webis plugin provides the colors and rough design of the Webis lecture notes. Start each page with a title and a short subtitle, and use badges for axiom names:

# Page Title

<p class="subtitle">Short description of the page</p>

<span class="badge">TFC1</span> `Tfc1Axiom` — _"Intuition of the axiom."_ [@key]

License¶

This repository is released under the MIT license. Files in the data/ directory are exempt from this license.