From 676847e4de6917ea0e83c585f0fbe0c1293cade7 Mon Sep 17 00:00:00 2001
From: James Braza <jamesbraza@gmail.com>
Date: Sun, 28 Jan 2024 23:01:34 -0800
Subject: [PATCH] Documenting tool integration (#104)

---
 docs/how_to_config.md | 72 +++++++++++++++++++++++++++++++++++++++++--
 docs/how_to_ignore.md | 24 ++++++++++++++-
 2 files changed, 93 insertions(+), 3 deletions(-)

diff --git a/docs/how_to_config.md b/docs/how_to_config.md
index e3f330b..3a8c7e8 100644
--- a/docs/how_to_config.md
+++ b/docs/how_to_config.md
@@ -56,23 +56,91 @@ bit more "Pythonic" and easier to read.)
 
 This is a template for `.pre-commit-config.yaml`:
 
+<table>
+<tr><th>As a native tool</th><th>As a flake8 plugin</th></tr>
+<tr><td>
+
 ```yaml
 - repo: https://github.com/jsh9/pydoclint
   rev: <latest_tag>
   hooks:
     - id: pydoclint
       args:
-        - [--style=google, --check-return-types=False]
+        - --style=google
+        - --check-return-types=False
 ```
 
+</td><td>
+
+```yaml
+- repo: https://github.com/pycqa/flake8
+  rev: <latest_tag>
+  hooks:
+    - id: flake8
+      additional_dependencies:
+        - pydoclint==<latest_tag>
+      args:
+        - --style=google
+        - --check-return-types=False
+```
+
+</td></tr>
+</table>
+
 If you've already specified all the configuration options in a config file,
 here is how to cite them in `.pre-commit-config.yaml`:
 
+<table>
+<tr><th>As a native tool</th><th>As a flake8 plugin</th></tr>
+<tr><td>
+
 ```yaml
 - repo: https://github.com/jsh9/pydoclint
   rev: <latest_tag>
   hooks:
     - id: pydoclint
       args:
-        - "--config=pyproject.toml"
+        - --config=pyproject.toml
+```
+
+</td><td>
+
+```yaml
+- repo: https://github.com/pycqa/flake8
+  rev: <latest_tag>
+  hooks:
+    - id: flake8
+      additional_dependencies:
+        - Flake8-pyproject>=1.2.0
+        - pydoclint==<latest_tag>
+      args:
+        - --toml-config=pyproject.toml
+        - --style=google
+        - --check-return-types=False
 ```
+
+</td></tr>
+</table>
+
+Here is an example accompanying `pyproject.toml` config file:
+
+<table>
+<tr><th>As a native tool</th><th>As a flake8 plugin</th></tr>
+<tr><td>
+
+```toml
+[tool.pydoclint]
+check-return-types = false
+style = "google"
+```
+
+</td><td>
+
+```toml
+[tool.flake8]
+check-return-types = false
+style = "google"
+```
+
+</td></tr>
+</table>
diff --git a/docs/how_to_ignore.md b/docs/how_to_ignore.md
index 91b4451..ca6fcd4 100644
--- a/docs/how_to_ignore.md
+++ b/docs/how_to_ignore.md
@@ -1,4 +1,12 @@
-# How to ignore certain violations in _flake8_ mode
+# How to ignore certain violations
+
+## As a native tool
+
+Currently, pydoclint does not support ignoring certain violations as a native
+tool. Please use it as a _flake8_ plugin to achieve that, or feel free to
+contribute this feature.
+
+## As a _flake8_ plugin
 
 In _flake8_ mode (meaning that you use _pydoclint_ as a flake8 plugin), if
 you'd like to ignore a specific violation code (such as `DOC201` and `DOC301`)
@@ -26,3 +34,17 @@ def my_function(  # noqa: DOC2
 All the usage is consistent with how you would use _flake8_. Please read the
 official _flake8_ documentation for full details:
 https://flake8.pycqa.org/en/latest/user/violations.html.
+
+### Usage with [Ruff](https://github.com/astral-sh/ruff)
+
+With `ruff>=0.1.3`, allowlist `DOC` codes using the
+[`external` setting](https://docs.astral.sh/ruff/settings/#external):
+
+Put the following in your `pyproject.toml` file:
+
+```toml
+[tool.ruff]
+external = [
+    "DOC",  # pydoclint
+]
+```