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