Closed Bug 1566097 Opened 5 years ago Closed 5 years ago

Register Sphinx specific directives in the RST linter


(Developer Infrastructure :: Source Documentation, task)

Not set


(firefox70 fixed)

Tracking Status
firefox70 --- fixed


(Reporter: ahal, Assigned: championshuttler)




(1 file)

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:

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:

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.

  1. 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.

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.

Attachment #9078729 - Attachment description: Bug 1566097 - Register Sphinx specific directives in the RST linter. r?ahal → Bug 1566097 - Setup rstcheck linter instead of restructuredtext-lint. r?ahal

As discussed with Andrew [ :ahal ] , now we are going to implement rstCheck linter ( instead of restructuredtext-lint ( because of the problems of registering Sphinx specific directives in restructuredtext-lint implemented initially in bug 1527361 , code is here at

Pushed by
Setup rstcheck linter instead of restructuredtext-lint. r=ahal
Closed: 5 years ago
Resolution: --- → FIXED
Target Milestone: --- → mozilla70
Product: Firefox Build System → Developer Infrastructure
You need to log in before you can comment on or make changes to this bug.