1527361 - Stand up restructuredtext-lint to catch problems in our documentation early

Status: RESOLVED FIXED

(Firefox Build System :: Documentation Infrastructure, enhancement)

Description

[Andrew Halberstadt [:ahal] (PTO until Aug 11th)]

Rst is not the easiest markup language to dive into. It would be great if we could catch common problems early with a linter. I found:
https://github.com/twolfson/restructuredtext-lint

There is a bit of documentation on standing up new linters here:
https://firefox-source-docs.mozilla.org/tools/lint/create.html

Comment 2

[Andrew Halberstadt [:ahal] (PTO until Aug 11th)]

Here are some tips for how I would go about completing this bug:

1. Create a dummy linter that just returns a hardcoded error. This can be the scaffolding you build off of. Make sure you can run it with:

   ./mach lint -l rst

   This creates the scaffolding and gives you an easy way to test.

2. Figure out how to bootstrap the restructured_text linter. You can copy the flake8 mechanism for this (i.e checkin a requirements.txt into the tree). You can use the hashin library to generate the hashes.

3. Implement the linter. This will importing restructuredtext_lint, running it on the specified files, and returning the results. You can use other linters as examples.

4. Define custom roles. Restructured text uses something called "roles". Sphinx has a bunch of custom roles that aren't in the main spec, so we'll need to tell the linter about them. You can see more info here:
   https://github.com/twolfson/restructuredtext-lint#extension

Comment 3

[Shivam Singhal [ :championshuttler ]]

Attachment: Bug 1527361 - Setup rst linter for the documentation. r=ahal

Comment 4

[Pulsebot]

Pushed by [e-mail]:
https://hg.mozilla.org/integration/autoland/rev/180fb2c33c4b
Setup rst linter for the documentation. r=ahal

Comment 5

[Bogdan Tara[:bogdan_tara | bogdant]]

https://hg.mozilla.org/mozilla-central/rev/180fb2c33c4b