Skip to content

Let --ignore take a comma-separated list - #171

Open
Eljees wants to merge 3 commits into
sphinx-contrib:mainfrom
Eljees:fix/113-ignore-accepts-a-list
Open

Eljees wants to merge 3 commits into
sphinx-contrib:mainfrom
Eljees:fix/113-ignore-accepts-a-list

Conversation

@Eljees

@Eljees Eljees commented Aug 14, 2026

Copy link
Copy Markdown

Fixes #113.

-i/--ignore is declared with action="append", so it takes exactly one value per flag. A second path handed to the same flag falls through to the positional argument list and is then reported as a path that does not exist:

$ sphinx-lint -i d1 d2 .
Error: path d2 does not exist

Three neighbouring options of the same parser — --enable, --disable and --sort-by — already take comma-separated values, so --ignore now does the same through a small ExtendIgnoreAction, while still accumulating across repeated flags. Both spellings work and can be mixed:

sphinx-lint -i d1,d2 .
sphinx-lint -i d1 -i d2 .

I did not use nargs="+", which the reporter suggested: with a greedy nargs, sphinx-lint -i d1 . would swallow the positional path as a second ignore value, so the command would lint nothing at all. The comma keeps the option and the positional arguments separable, and it matches what the rest of the parser already does.

A second defect fell out of this

Today an empty value silences the entire run:

$ sphinx-lint -i "" .          # reports nothing at all

walk() skips a path when an ignored value is a substring of it, and the empty string is a substring of every path. Empty values are now dropped, so -i "" is a no-op rather than a global mute. That is one of the four tests.

Measured

On c6d82b7:

result
baseline, clean tree 110 passed, 1 skipped, 0 failed
new tests, before the fix 2 failed, 2 passed
new tests, after the fix 4 passed
full suite, after the fix 114 passed, 1 skipped, 0 failed

The two that fail before the fix are the comma-separated list and the empty value; the other two cover a single -i and repeated -i flags, which already worked and must keep working.

ruff check and ruff format --check at the pinned v0.15.20 are clean on both changed files, and ruff check is equally clean on an untouched checkout. The man page entry for -i is updated to match.

AI-assisted (LLM used for drafting); the runs above are mine.

-i/--ignore used action=append, so a second path passed to the same
flag was consumed as a positional argument and reported as a missing
path. Three neighbouring options of the same parser (--enable,
--disable, --sort-by) already accept comma-separated values, so this
makes --ignore behave the same way while still accumulating across
repeated flags.

An empty value is now dropped instead of being kept: the empty string
is a substring of every path, so -i '' silently ignored the whole run.

Fixes sphinx-contrib#113

@m-aciek m-aciek left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good to me

@Eljees

This comment was marked as resolved.

@hugovk

This comment was marked as resolved.

@Eljees

This comment was marked as resolved.

@hugovk

This comment was marked as resolved.

@Eljees

Eljees commented Sep 25, 2026

Copy link
Copy Markdown
Author

I merged main into this branch and into #172, now that #174 and #175 are in. The workflows are waiting for approval again. With those two in, Deploy should pass as well.

@hugovk hugovk left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I did not use nargs="+", which the reporter suggested: with a greedy nargs, sphinx-lint -i d1 . would swallow the positional path as a second ignore value, so the command would lint nothing at all. The comma keeps the option and the positional arguments separable, and it matches what the rest of the parser already does.

Good point.

Although splitting a comma-separated string means you can no longer ignore a path with a comma in it: --ignore abc,def ignores abc and def, but won't ignore a abc,def/ directory.

Do we care about this?

Comment thread tests/test_issue_113.py
@@ -0,0 +1,53 @@
"""Tests for issue #113: ``--ignore`` should accept a list of paths."""

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No need to reference the issue number here or in the test filename. Call it test_ignore.py?

This file doesn't need to be executable.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also these tests could be in a single test function using @pytest.mark.parametrize.

Comment thread sphinx-lint.1

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

And give an example in the README?

Comment thread tests/test_issue_113.py
@pytest.fixture
def tree(tmp_path):
"""Build a tree with two ignorable subdirs, each holding a faulty file."""
for name in ("d1", "d2"):

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A macOS temp dir can be like /var/folders/p6/lf2s1s5d4kb335g2d1td8z8c0000gn/T which can match d1.

Let's rename these throughout, perhaps something like:

Suggested change
for name in ("d1", "d2"):
for name in ("ignored_dir1", "ignored_dir2"):

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

-i --ignore flag doesn't accept a list of arguments

3 participants