User defined directives, roles, etc to ignore

[peterjc]

I'm aware of #26 which added an example of registering a directive (which would allow full validation), but how about making it easy to ignore user defined lists of non-standard RST directives, roles, etc?

I am thinking along these lines, a recent change to my flake8-rst-docstrings (which calls into restructuredtext-lint to get docutils to validate RST extracted from docstrings in Python code):

peterjc/flake8-rst-docstrings#16

As an aside, are substitutions common enough to need handling too? e.g. Using this for version seems quite common.

[twolfson]

Hmm, I'm not sure I fully understand the issue. To paraphrase my understanding, this is so people can write more advanced RST and then only lint the more basic components?

Maybe we could encourage people to use a stub directive in this case? I guess we could make that easy programattically -- unsure about the need for this on the CLI though

[peterjc]

Yes, that paraphrasing is accurate.

I want to be able to use rst-lint as a quick check for a pre-commit hook and/or early step in continuous integration - with a dedicated continuous integration building the documentation later if that all seems fine (e.g. sphinx, which is slow).

To that end, being able to tell rst-lint a list of additional known roles, directives (and maybe substitutions) would be useful (even if it cannot fully validate the more complex RST extensions).

A command line switch which sets up stub directives would be fine. I was thinking just a command line switch which silences the associated warnings (as done on the flake8 plugin).

[twolfson]

We do have a CLI flag for different log levels. I'm guessing moving to error only isn't good enough?

[peterjc]

Sadly no, Unknown interpreted text role, Unknown directive type and Undefined substitution referenced are all error level.

Quoting myself from PyCQA/pydocstyle#396 (comment)

$ rst-lint docs/*.rst docs/*/*.rst
ERROR docs/error_codes.rst:23 Unknown interpreted text role "ref".
ERROR docs/index.rst:19 Unknown directive type "toctree".
ERROR docs/snippets/config.rst:39 Unknown interpreted text role "ref".
ERROR docs/snippets/pre_commit.rst:232 Undefined substitution referenced: "version".
ERROR docs/snippets/config.rst:39 Unknown interpreted text role "ref".
ERROR docs/snippets/pre_commit.rst:6 Undefined substitution referenced: "version".

Here I would like to be able to do something like the following, passing comma-separated lists of roles, directives and substitutions to ignore:

$ rst-lint --roles ref --directives toctree --substitutions version docs/*.rst docs/*/*.rst
(no error)

As a bonus, I should then also be able to simplify flake8-rst-docstrings by passing my lists of known roles and directives when calling your code (rather than filtering the results I get back).

--

Perhaps we should leave this issue open a while, and see if there are other user perspectives which might help decide this?

[twolfson]

Okay, cool. This is good foundation indeed. The proposal to leaving this issue open sounds fantastic to me. I'm about to go offline for a month (very heads down until then (building giant art)) so we can revisit this when I get back =)

[AyanSinhaMahapatra]

I want to be able to use rst-lint as a quick check for a pre-commit hook and/or early step in continuous integration - with a dedicated continuous integration building the documentation later if that all seems fine (e.g. sphinx, which is slow).

Hi, I was also looking into rst-lint for similar requirements as @peterjc and it will be much appreciated.

[peterjc]

Someone recently drew my attention to a similar tool called rstcheck which also wraps docutils for RST validation:

https://github.com/myint/rstcheck

This offers command line settings --ignore-directives and --ignore-roles as discussed here which can also be used via Python (and it has other ignore lists like substitutions).

The other big feature is it can check the syntax of some code blocks within the RST (e.g. a block of JSON or XML) - indeed this was originally the only thing this tool did back at v0.1 six years ago.