Closed Bug 1527361 Opened 3 years ago Closed 2 years ago

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

Categories

(Firefox Build System :: Documentation Infrastructure, enhancement)

enhancement
Not set
normal

Tracking

(firefox70 fixed)

RESOLVED FIXED
mozilla70
Tracking Status
firefox70 --- fixed

People

(Reporter: ahal, Assigned: championshuttler)

References

(Blocks 1 open bug)

Details

Attachments

(1 file)

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

Duplicate of this bug: 1537759

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

Assignee: nobody → shivams2799
Status: NEW → ASSIGNED
Pushed by ahalberstadt@mozilla.com:
https://hg.mozilla.org/integration/autoland/rev/180fb2c33c4b
Setup rst linter for the documentation. r=ahal
Status: ASSIGNED → RESOLVED
Closed: 2 years ago
Resolution: --- → FIXED
Target Milestone: --- → mozilla70
Regressions: 1598615
You need to log in before you can comment on or make changes to this bug.