Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .github/CODEOWNERS
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
* @forman @clarasb
44 changes: 19 additions & 25 deletions .github/workflows/publish.yml
Original file line number Diff line number Diff line change
Expand Up @@ -11,29 +11,27 @@ jobs:
strategy:
fail-fast: false
matrix:
python-version: ["3.10", "3.11", "3.12", "3.13"]
environment: [py310, py311, py312, py313]

steps:
- uses: actions/checkout@v3
- uses: actions/checkout@v4

- name: Set up Python ${{ matrix.python-version }}
uses: actions/setup-python@v3
- name: Set up Pixi
uses: prefix-dev/setup-[email protected]
with:
python-version: ${{ matrix.python-version }}
pixi-version: v0.84.2
environments: ${{ matrix.environment }}
cache-key: pixi-${{ matrix.environment }}-
locked: true

- name: Install dependencies
run: |
python -m pip install --upgrade pip
pip install .[dev,doc]
- name: Check formatting with Ruff
run: pixi run --locked -e ${{ matrix.environment }} format --check

- name: Lint with ruff
run: |
ruff check
- name: Lint with Ruff
run: pixi run --locked -e ${{ matrix.environment }} checks

- name: Run unit tests
shell: bash -l {0}
run: |
pytest --cov=xrlint --cov-branch --cov-report=xml
run: pixi run --locked -e ${{ matrix.environment }} tests --cov=xrlint --cov-branch --cov-report=xml

- name: Upload coverage reports to Codecov
uses: codecov/codecov-action@v5
Expand All @@ -50,19 +48,15 @@ jobs:
steps:
- uses: actions/checkout@v4

- name: Set up Python
uses: actions/setup-python@v5
- name: Set up Pixi
uses: prefix-dev/setup-[email protected]
with:
python-version: '3.x'

- name: Install dependencies
run: |
python -m pip install --upgrade pip
pip install build
pixi-version: v0.84.2
cache-key: pixi-default-
locked: true

- name: Build package
run: |
python -m build
run: pixi run --locked build

- name: Publish package to PyPI
uses: pypa/gh-action-pypi-publish@27b31702a0e7fc50959f5ad993c78deac1bdfc29
Expand Down
31 changes: 13 additions & 18 deletions .github/workflows/tests.yml
Original file line number Diff line number Diff line change
@@ -1,7 +1,3 @@
# This workflow will install Python dependencies, run tests and lint
# with a variety of Python versions. For more information see:
# https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python

name: tests

on:
Expand All @@ -17,24 +13,23 @@ jobs:
strategy:
fail-fast: false
matrix:
python-version: ["3.10", "3.11", "3.12", "3.13"]
environment: [py310, py311, py312, py313]

steps:
- uses: actions/checkout@v3
- name: Set up Python ${{ matrix.python-version }}
uses: actions/setup-python@v3
- uses: actions/checkout@v4
- name: Set up Pixi
uses: prefix-dev/setup-[email protected]
with:
python-version: ${{ matrix.python-version }}
- name: Install dependencies
run: |
python -m pip install --upgrade pip
pip install .[dev,doc]
- name: Lint with ruff
run: |
ruff check
pixi-version: v0.84.2
environments: ${{ matrix.environment }}
cache-key: pixi-${{ matrix.environment }}-
locked: true
- name: Check formatting with Ruff
run: pixi run --locked -e ${{ matrix.environment }} format --check
- name: Lint with Ruff
run: pixi run --locked -e ${{ matrix.environment }} checks
- name: Test with pytest
run: |
pytest --cov=xrlint --cov-branch --cov-report=xml
run: pixi run --locked -e ${{ matrix.environment }} tests --cov=xrlint --cov-branch --cov-report=xml
- name: Upload coverage reports to Codecov
uses: codecov/codecov-action@v5
with:
Expand Down
4 changes: 3 additions & 1 deletion .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,8 @@ __pycache__
coverage.xml
htmlcov/
site/
.cache/
docs/rule-ref.md

# Jupyter
.ipynb_checkpoints
Expand All @@ -35,4 +37,4 @@ notebooks/*.zarr/
.idea/

# Downloaded assets
docs/assets/downloaded/
docs/assets/downloaded/
9 changes: 9 additions & 0 deletions CHANGES.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,11 @@

### Documentation

- Migrated from MkDocs/Material to Zensical with the classic theme and
`zensical.toml`. Preserved the existing Pixi documentation commands, self-hosted
fonts, API references, and automatic rule-reference regeneration during preview.
Moved documentation helpers into `docs/scripts/` and added dated migration notes
covering dependency versions and remaining compatibility limitations. (#81)
- Completed the configuration guide, replacing all "Coming soon" sections with
explanations and examples for file filters, opening options, rule settings,
presets, custom plugins, rules, and processors.
Expand All @@ -16,6 +21,10 @@
ACDD 1.1 and strict-recommended preset limitations, including a working override
for the latter.

### Other Changes

- Now using [Pixi](https://pixi.prefix.dev/latest/) as project management tool. (#80)


## Version 0.6.0 (from 2026-09-11)

Expand Down
82 changes: 51 additions & 31 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,27 +8,23 @@ Code and configuration changes must be linked to a corresponding issue.

## Development setup

Use Python 3.10 or newer. From the repository root, install the project in
editable mode with development and documentation dependencies:
From the repository root, install the development environment with Pixi.

```bash
python -m pip install -e ".[dev,doc]"
pixi install
```

An editable installation also registers the `xrlint` command and built-in plugin
entry points. Merely adding the source directory to `PYTHONPATH` does not register
those entry points.

If using conda or mamba, create and activate the repository environment, then
install the project and extras to include dependencies declared in
`pyproject.toml`:
Run the development tasks in this order from the same directory.

```bash
conda env create -f environment.yml
conda activate xrlint
python -m pip install -e ".[dev,doc]"
pixi run format
pixi run checks
pixi run tests
```

Pixi installs XRLint in editable mode and registers the `xrlint` command and
built-in plugin entry points.

## Project layout

| Path | Responsibility |
Expand All @@ -45,29 +41,28 @@ python -m pip install -e ".[dev,doc]"

## Checks before submitting

Run the checks relevant to your change from the repository root:
Run the checks relevant to your change from the repository root.

```bash
python -m ruff format --check
python -m ruff check
python -m pytest --cov=xrlint --cov-branch --cov-report=html
python -m mkdocs build --strict
pixi run format --check
pixi run checks
pixi run tests --cov=xrlint --cov-branch --cov-report=html
```

- Keep existing tests passing and add coverage for new or changed behavior.
- Aim to keep coverage close to 100%; review the report in `htmlcov/index.html`.
- Update documentation and examples when behavior or configuration changes.
- For documentation changes, preview the site with `python -m mkdocs serve`
and verify links, code blocks, and generated references.
- For documentation changes, follow [Building documentation](#building-documentation)
to build and preview the site. Verify links, code blocks, and generated references.
- Describe the problem, resulting behavior, and validation in the pull request.

## Code style

Use Ruff's formatter and linter with the repository configuration:
Use the Pixi tasks to run Ruff's formatter and linter with the repository configuration.

```bash
python -m ruff format
python -m ruff check
pixi run format
pixi run checks
```

Group imports in this order: future imports, standard library, third-party
Expand Down Expand Up @@ -121,21 +116,46 @@ See [Custom Plugins](docs/config.md#custom-plugins).

## Building documentation

The default Pixi environment includes the documentation dependencies. From the
repository root, build or preview the site with the documentation tasks.

```bash
python -m mkdocs build --strict
python -m mkdocs serve
pixi run docs-build
pixi run docs-serve
```

The build writes `site/`. The preview command serves the site locally and
rebuilds when files change. Edit Markdown pages in `docs/`; update `mkdocs.yml`
rebuilds when files change. Edit Markdown pages in `docs/`; update `zensical.toml`
when adding navigation entries.

`docs/mkruleref.py` runs automatically through `mkdocs-gen-files`, generating
`rule-ref.md` from discovered plugin metadata. Do not create or edit that
generated page manually. Update rule descriptions and schemas in the source,
or change the generator for presentation changes. The API page uses
`mkdocstrings` to render source docstrings.
Both tasks use `docs/scripts/manage.py` to prepare self-hosted Roboto fonts and run
`docs/scripts/mkruleref.py`, generating the ignored `docs/rule-ref.md` from discovered
plugin metadata. The build then runs `zensical build --strict`; preview runs
`zensical serve`. Additional arguments are forwarded, for example
`pixi run docs-serve --dev-addr 127.0.0.1:8001`.

During preview, a watcher checks Python sources in `xrlint/`, the generator,
and `pyproject.toml` every half second. Changes regenerate the reference in a
fresh Python process, and Zensical reloads the page. If an edit temporarily breaks
generation, the last successful page remains available; fixing the source retries
generation. Stop preview with Ctrl+C.

Do not create or edit the generated rule page manually. Update rule descriptions
and schemas in the source, or change the generator for presentation changes.
The API page uses `mkdocstrings` to render source docstrings. Use these Pixi tasks
instead of invoking Zensical directly so preparation and regeneration take place.
See [migration notes](docs/zensical-migration.md) for compatibility limitations.

The plugins installed in the build environment determine the generated rule
reference. Use a project environment without unrelated third-party XRLint
plugins when building the project's published documentation.

## Building packages

Build the wheel and source distribution from the repository root.

```bash
pixi run build
```

The build writes the distribution files to `dist/`.
24 changes: 10 additions & 14 deletions docs/about.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,29 +22,25 @@ Code and configuration pull requests must reference a corresponding issue.

## Development

From a repository checkout, install the project and its development extras:
From the repository root, install the development environment with Pixi, then
format the code, run lint checks, and run the tests.

```bash
python -m pip install -e ".[dev,doc]"
python -m ruff check
python -m pytest --cov=xrlint --cov-branch --cov-report=html
pixi install
pixi run format
pixi run checks
pixi run tests --cov=xrlint --cov-branch --cov-report=html
```

Editable installation registers the command and plugin entry points needed by
the tests and documentation generator. See the contribution guide for conda
setup, code style, and the project layout.
The contribution guide also covers code style and project layout.

## Documentation

Build and preview from the repository root:

```bash
python -m mkdocs build --strict
python -m mkdocs serve
```
Follow the [documentation build and preview instructions](https://github.com/bcdev/xrlint/blob/main/CONTRIBUTING.md#building-documentation)
to set up MkDocs and run it locally.

The generated site is written to `site/`. The rule reference is generated by
`docs/mkruleref.py` during the build, using installed plugin metadata.
`docs/scripts/mkruleref.py` during the build, using installed plugin metadata.
The API reference is rendered from Python docstrings by `mkdocstrings`.

## License
Expand Down
4 changes: 1 addition & 3 deletions docs/config.md
Original file line number Diff line number Diff line change
Expand Up @@ -369,9 +369,7 @@ class RequiredTitle(RuleOp):
)


plugin.define_config(
"recommended", {"rules": {"project/required-title": "error"}}
)
plugin.define_config("recommended", {"rules": {"project/required-title": "error"}})


def export_plugin():
Expand Down
7 changes: 4 additions & 3 deletions docs/examples.md
Original file line number Diff line number Diff line change
Expand Up @@ -91,11 +91,12 @@ or `kwargs` to `RuleTest`.

Use `RuleTester.define_test()` to generate a `unittest.TestCase` class discoverable
by pytest. The [rule_testing.py example](https://github.com/bcdev/xrlint/blob/main/examples/rule_testing.py)
demonstrates both approaches:
demonstrates both approaches. Run these commands from the repository root after
`pixi install`.

```bash
python -m examples.rule_testing
python -m pytest tests/test_examples.py
pixi run python -m examples.rule_testing
pixi run tests tests/test_examples.py
```

## API usage
Expand Down
12 changes: 7 additions & 5 deletions docs/hooks/download_fonts.py → docs/scripts/download_fonts.py
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
from pathlib import Path
from pathlib import Path
from urllib.error import URLError
from urllib.request import urlretrieve

Expand All @@ -20,9 +20,9 @@
)


def on_config(config):
"""Download self-hosted Roboto assets before MkDocs builds the site."""
docs_dir = Path(config["docs_dir"])
def download_fonts():
"""Prepare self-hosted Roboto assets before building or previewing the site."""
docs_dir = Path(__file__).resolve().parent.parent
font_dir = docs_dir / "assets" / "downloaded" / "fonts"
font_dir.mkdir(parents=True, exist_ok=True)

Expand All @@ -41,4 +41,6 @@ def on_config(config):
f"{font_dir}."
) from exc

return config

if __name__ == "__main__":
download_fonts()
Loading
Loading