sphinx-lint
sphinx-lint copied to clipboard
sphinx-contrib
Ignore markup errors in comments
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?
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
I would ignore markup in comments, just as (I assume) Sphinx also does.
Similar to https://github.com/sphinx-contrib/sphinx-lint/issues/34, where we want to ignore markup inside code blocks.
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.
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
There is a check for comments, but only on the same line -- the in_literal state logic could be expanded to comments?
https://github.com/sphinx-contrib/sphinx-lint/blob/b3775563717e4c875cabd0e6709c47094a8d0bfa/sphinxlint.py#L511-L512
A