Ignore markup errors in comments

[ezio-melotti]

I ran sphinx-lint against a project that includes the following in the index.rst:

.. <project name> documentation master file, created by
   sphinx-quickstart on Sat Aug 28 22:34:16 2021.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

Since I was using the --enable default-role option, I got the following error, even though the markup appears in a comment:

index.rst:4: default role used (hint: for inline literals, use double backticks) (default-role)

Should sphinx-lint ignore markup errors in a comment?

[AA-Turner]

Perhaps a flag to ignore comments? Sometimes when writing documentation I comment things out that I want to return to later. However that is a niche use-case---Ezio's example is probably more common where people don't care about the markup in comments.

A

[hugovk]

I would ignore markup in comments, just as (I assume) Sphinx also does.

Similar to #34, where we want to ignore markup inside code blocks.

[ezio-melotti]

As far as I know sphinx-lint works line by line, without parsing the markup (it only uses regexes), so this might be tricky to implement unless we change it to handle more context.

[AA-Turner]

Docutils (and hence also Sphinx) just includes the text verbatim in a comment node:

(docutils) S:\Development\docutils>type comment-test.rst
.. This is a reStructuredText comment with :pep`42`` misformed markup.

(docutils) S:\Development\docutils>docutils --writer pseudoxml comment-test.rst
<document source="comment-test.rst">
    <comment xml:space="preserve">
        This is a reStructuredText comment with :pep`42`` misformed markup.

A

[AA-Turner]

There is a check for comments, but only on the same line -- the in_literal state logic could be expanded to comments?

sphinx-lint/sphinxlint.py

Lines 511 to 512 in b377556

	elif re.match(r" *\.\. ", line) and type_of_explicit_markup(line) == "comment":
	line = "\n"

A