From fa41757fb29525bfd9ffb71d1a8f5f423e7a3104 Mon Sep 17 00:00:00 2001
From: "jsh9, PhD" <25124332+jsh9@users.noreply.github.com>
Date: Wed, 7 Feb 2024 03:07:10 -0500
Subject: [PATCH] Add option to show filename for each violation msg (#119)

Partially contributed by @gigi-minds-ai
---
 CHANGELOG.md           | 11 +++++++++++
 docs/config_options.md | 39 +++++++++++++++++++++++++++++++++++++--
 pydoclint/main.py      | 32 ++++++++++++++++++++++++++------
 setup.cfg              |  2 +-
 4 files changed, 75 insertions(+), 9 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 4c782a7..d3ac128 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,16 @@
 # Change Log
 
+## [0.3.10] - 2024-02-07
+
+- Added
+
+  - A new config option `--show-filenames-in-every-violation-message` (or
+    `-sfn`), which makes it more convenient to jump to the corresponding line
+    in IDEs by clicking on the violation message in the terminal
+
+- Full diff
+  - https://github.com/jsh9/pydoclint/compare/0.3.9...0.3.10
+
 ## [0.3.9] - 2024-01-16
 
 - Fixed
diff --git a/docs/config_options.md b/docs/config_options.md
index 15d2279..2e1f39a 100644
--- a/docs/config_options.md
+++ b/docs/config_options.md
@@ -24,7 +24,8 @@ page:
 - [11. `--check-yield-types` (shortform: `-cyt`, default: `True`)](#11---check-yield-types-shortform--cyt-default-true)
 - [12. `--baseline`](#12---baseline)
 - [13. `--generate-baseline` (default: `False`)](#13---generate-baseline-default-false)
-- [14. `--config` (default: `pyproject.toml`)](#14---config-default-pyprojecttoml)
+- [14. `--show-filenames-in-every-violation-message` (shortform: `-sfn`, default: `False`)](#14---show-filenames-in-every-violation-message-shortform--sfn-default-false)
+- [15. `--config` (default: `pyproject.toml`)](#15---config-default-pyprojecttoml)
 
 <!--TOC-->
 
@@ -189,7 +190,41 @@ in that file.
 Required to use with `--baseline` option. If `True`, generate the baseline file
 that contains all current violations.
 
-## 14. `--config` (default: `pyproject.toml`)
+## 14. `--show-filenames-in-every-violation-message` (shortform: `-sfn`, default: `False`)
+
+If False, in the terminal the violation messages are grouped by file names:
+
+```
+file_01.py
+    10: DOC101: ...
+    25: DOC105: ...
+    37: DOC203: ...
+
+file_02.py
+    24: DOC102: ...
+    51: DOC107: ...
+    126: DOC203: ...
+    246: DOC105: ...
+```
+
+If True, the file names are printed in the front of every violation message:
+
+```
+file_01.py:10: DOC101: ...
+file_01.py:25: DOC105: ...
+file_01.py:37: DOC203: ...
+
+file_02.py:24: DOC102: ...
+file_02.py:51: DOC107: ...
+file_02.py:126: DOC203: ...
+file_02.py:246: DOC105: ...
+```
+
+This can be convenient if you would like to click on each violation message and
+go to the corresponding line in your IDE. (Note: not all terminal app offers
+this functionality.)
+
+## 15. `--config` (default: `pyproject.toml`)
 
 The full path of the .toml config file that contains the config options. Note
 that the command line options take precedence over the .toml file. Look at this
diff --git a/pydoclint/main.py b/pydoclint/main.py
index 32335ac..c7c07f9 100644
--- a/pydoclint/main.py
+++ b/pydoclint/main.py
@@ -227,6 +227,14 @@ def validateStyleValue(
         ' file should be specified by the --baseline option.)'
     ),
 )
+@click.option(
+    '-sfn',
+    '--show-filenames-in-every-violation-message',
+    type=bool,
+    show_default=True,
+    default=False,
+    help='If True, show file names in the front of every violation message.',
+)
 @click.argument(
     'paths',
     nargs=-1,
@@ -283,6 +291,7 @@ def main(  # noqa: C901
         require_yield_section_when_yielding_nothing: bool,
         generate_baseline: bool,
         baseline: str,
+        show_filenames_in_every_violation_message: bool,
         config: Optional[str],  # don't remove it b/c it's required by `click`
 ) -> None:
     """Command-line entry point of pydoclint"""
@@ -433,14 +442,25 @@ def main(  # noqa: C901
                 if counter > 1:
                     print('')
 
-                click.echo(
-                    click.style(filename, fg='yellow', bold=True),
-                    err=echoAsError,
-                )
+                if not show_filenames_in_every_violation_message:
+                    click.echo(
+                        click.style(filename, fg='yellow', bold=True),
+                        err=echoAsError,
+                    )
+
                 for violation in violationsInThisFile:
                     violationCounter += 1
-                    fourSpaces = '    '
-                    click.echo(fourSpaces, nl=False, err=echoAsError)
+                    if not show_filenames_in_every_violation_message:
+                        fourSpaces = '    '
+                        click.echo(fourSpaces, nl=False, err=echoAsError)
+                    else:
+                        click.echo(
+                            click.style(filename, fg='yellow', bold=True),
+                            nl=False,
+                            err=echoAsError,
+                        )
+                        click.echo(':', nl=False, err=echoAsError)
+
                     click.echo(
                         f'{violation.line}: ', nl=False, err=echoAsError
                     )
diff --git a/setup.cfg b/setup.cfg
index aef804a..586c08e 100644
--- a/setup.cfg
+++ b/setup.cfg
@@ -1,6 +1,6 @@
 [metadata]
 name = pydoclint
-version = 0.3.9
+version = 0.3.10
 description = A Python docstring linter that checks arguments, returns, yields, and raises sections
 long_description = file: README.md
 long_description_content_type = text/markdown