1566097 - Register Sphinx specific directives in the RST linter

Status: RESOLVED FIXED

(Developer Infrastructure :: Source Documentation, task)

Description

[Andrew Halberstadt [:ahal]]

In bug 1527361 Shivam is working on a new restructuredtext linter to help with our documentation. But out of the box, the underlying linter doesn't know about custom Sphinx directives (it just lints to the core rst spec). We'll need to tell it about these custom directives otherwise it'll think they are all errors.

Here is an example of how to do so:
https://github.com/twolfson/restructuredtext-lint#extension

In the other bug we ran the restructuredtext-lint binary via the subprocess module. I think we'll need to stop doing this and instead call that lint_file function directly. So roughly here are some steps for this bug:

1. Get the linter working without the use of subprocess. This will involve taking the files passed into our lint function and expanding any directories into a list of rst files contained by those directories. You can use this helper function:
   https://searchfox.org/mozilla-central/source/python/mozlint/mozlint/pathutils.py#247

Then you will need to loop over each returned file, calling lint_file on it one at a time and adding any resulting errors to the results object.

2. Next you'll need to start registering directives and roles. To do this I'd recommend adding a single file to the include (or removing it from the exclude), and seeing what fails. Then you can try to register any unknown directives/roles that the linter is complaining about and see if those errors go away. Once the errors are all gone, try it again with another couple files.

Comment 1

[Andrew Halberstadt [:ahal]]

Hey Shivam, I'd suggest to start by changing the single "include" line to tools/lint/docs to start and trying to fix those issues.

Comment 2

[Shivam Singhal [ :championshuttler ]]

Attachment: Bug 1566097 - Setup rstcheck linter instead of restructuredtext-lint. r?ahal

Comment 3

[Shivam Singhal [ :championshuttler ]]

As discussed with Andrew [ :ahal ] , now we are going to implement rstCheck linter (https://github.com/myint/rstcheck) instead of restructuredtext-lint (https://github.com/twolfson/restructuredtext-lint) because of the problems of registering Sphinx specific directives in restructuredtext-lint implemented initially in bug 1527361 , code is here at https://phabricator.services.mozilla.com/D36586.

Comment 4

[Pulsebot]

Pushed by [e-mail]:
https://hg.mozilla.org/integration/autoland/rev/35c99c4a6738
Setup rstcheck linter instead of restructuredtext-lint. r=ahal

Comment 5

[Alexandru Michis [:malexandru]]

https://hg.mozilla.org/mozilla-central/rev/35c99c4a6738