Project proposal: lint rst single vs double backticks

[jayvdb]

There isnt any clear guidance on single vs double backticks in RST, especially when RST is not embedded within Python, however a rule of thumb is that single backticks should be implicit references to something.

https://stackoverflow.com/questions/22256995/restructuredtext-in-sphinx-and-docstrings-single-vs-double-back-quotes-or-back https://mail.zope.org/pipermail/grok-dev/2008-December/006823.html

For documentation especially, it would be helpful to have a checker that finds a section heading somewhere in the docs for anything in single backticks, and errors if it cant be found.

https://github.com/myint/rstcheck would likely be the best spot for this to be implemented.

And https://github.com/myint/rstcheck/issues/32 would be an ideal task to be done to familiarise oneself with the project.

[jayvdb]

We would need to add lots of other checks to make this a full three month project.

Scope probably should be validation of docstring text markup in general, which is a subset of the nested language space (https://github.com/coala/projects/issues/547)

[ankitxjoshi]

The phases of the project can be =>

• Enhance rstcheck to return column offset wherever applicable.
• Implement the single vs double backticks check
• Modify RSTcheckBear to provide fixes logic for some solvable errors.

In the initial phase along with modification related to column offset, some side work could be done to provide errors in json format. With these changes the student would get a thorough knowledge of the codebase.

The second phase would be mainly to design and code the enhancement logic.

In the final phase it would be better to provide fixes logic for some, not all errors. One good and simple fixes can be for the Link formatted in Markdown style. The fixes will not be part of rstcheck but would be done in RSTcheckBear.