From 32dfbb59fe73c820fd1c5d43613fa40fe3efde7d Mon Sep 17 00:00:00 2001
From: KK <dev-kk@oeaw.ac.at>
Date: Thu, 16 May 2024 16:34:05 +0200
Subject: [PATCH] docs(poetry-ruff): add documentation for Ruff workflow

Closes: #69
---
 README.md           |  3 +--
 docs/poetry-ruff.md | 63 +++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 64 insertions(+), 2 deletions(-)
 create mode 100644 docs/poetry-ruff.md

diff --git a/README.md b/README.md
index 59940b5..4eabf82 100644
--- a/README.md
+++ b/README.md
@@ -17,5 +17,4 @@ various repositories of the Prosopograhy and Networks group at the
 * poetry-deptry.yml
 
 * poetry-djlint.yml
-
-* poetry-ruff.yml
+* [poetry-ruff](docs/poetry-ruff.md)
diff --git a/docs/poetry-ruff.md b/docs/poetry-ruff.md
new file mode 100644
index 0000000..2af6ed3
--- /dev/null
+++ b/docs/poetry-ruff.md
@@ -0,0 +1,63 @@
+# Documentation for `poetry-ruff.yml` workflow
+
+[poetry-ruff.yml](../.github/workflows/poetry-ruff.yml) is a reusable GitHub workflow for the [Ruff](https://docs.astral.sh/ruff/) linter and code formatter for Python.
+
+
+## How to use
+
+The Ruff workflow can be used for either [linting](https://docs.astral.sh/ruff/linter/) or [formatting](https://docs.astral.sh/ruff/formatter/) – or both.
+
+If you need only one of these, create one new workflow file in all repositories whose files should get inspected by Ruff. If you need both, create two separate new workflow files.
+
+Ruff differentiates between formatting and linting based on arguments with which it is called. When not configured otherwise, the parent Prosnet workflow defaults to _linting_.
+
+
+The following example config runs the [Ruff linter](https://docs.astral.sh/ruff/formatter/) on all pull requests:
+
+```yml
+name: Run Ruff linter
+
+on: pull_request
+
+jobs:
+  ruff-linter:
+    uses: acdh-oeaw/prosnet-workflows/.github/workflows/poetry-ruff.yml@RELEASE_VERSION
+    with:
+      src: "."
+```
+
+
+This second examples runs the [Ruff formatter](https://docs.astral.sh/ruff/formatter/) on all PRs:
+
+```yml
+name: Run Ruff formatter
+
+on: pull_request
+
+jobs:
+  ruff-formatter:
+    uses: acdh-oeaw/prosnet-workflows/.github/workflows/poetry-ruff.yml@RELEASE_VERSION
+    with:
+      src: "."
+      options: "format --check"
+```
+
+### Required settings
+
+* `RELEASE_VERSION` needs to be set to a valid prosnet-workflows [release tag](https://github.com/acdh-oeaw/prosnet-workflows/releases), branch name or SHA.
+* `src` refers to the path from which Ruff will work its way down the hierarchical file structure. The example uses `"."`, the current working directory, which may serve you best. Only change it if you need Ruff to start from a different directory instead.
+
+
+### Optional settings
+
+The following optional variables can be added to the `with` section of the config:
+
+* `options`: Arguments with which to run `poetry run ruff`. Default is `check`, which runs Ruff as linter. Set this explicitly to override the default, e.g. use `format` to run Ruff as code formatter. See the Ruff [linter](https://docs.astral.sh/ruff/linter/) and [formatter](https://docs.astral.sh/ruff/formatter/) docs for details on more fine-grained settings.
+* `python-version`: The Python version for which to set up Poetry, which is used to run Ruff. For APIS projects, the prosnet-workflows default should work best.
+
+
+**Other configurations**
+
+The `name` of your workflow can be whatever makes sense to you. It's how the workflow will show up in the "Actions" tab.
+
+If you use two Ruff workflows in the same repository, take care to name them differently to make it easier to differentiate workflow runs. The same applies to the `jobs` section in the config as well as the file names themselves.