Closed Bug 1566097 Opened Last month Closed Last month

Register Sphinx specific directives in the RST linter

Categories

(Firefox Build System :: Generated Documentation, task)

task
Not set

Tracking

(firefox70 fixed)

RESOLVED FIXED
mozilla70
Tracking Status
firefox70 --- fixed

People

(Reporter: ahal, Assigned: championshuttler)

References

Details

Attachments

(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:
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.

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

Pushed by ahalberstadt@mozilla.com:
https://hg.mozilla.org/integration/autoland/rev/35c99c4a6738
Setup rstcheck linter instead of restructuredtext-lint. r=ahal
Status: ASSIGNED → RESOLVED
Closed: Last month
Resolution: --- → FIXED
Target Milestone: --- → mozilla70
You need to log in before you can comment on or make changes to this bug.