Hi,
I am trying to help the LLVM dev group by converting existing HTML
documentation into reSt. During that conversion stage, we've discovered
some frequently occuring mishaps in our documents that I'd like Sphinx to
catch, if possible. Currently, I am using a tiny Python script (see the
attached file) to check for these inconsistencies, but it would be very
nifty if Sphinx could catch them on its own.
The three checks are:
1. Trailing whitespace in lines.
2. Too long or too short section marker (the ===/---/^^^^ line is
shorter than or longer than the text that preceeds it).
3. Too long lines: the LLVM group uses as standard 80 chars per line so
it would be nice with a warning, possibly by adding a new option (-maxlen
or whatever).
The three checks are all cosmetic and does not affect the behavior of
Sphinx as far as I know.
Regards,
Mikael
--
You received this message because you are subscribed to the Google Groups
"sphinx-dev" group.
To view this discussion on the web visit
https://groups.google.com/d/msg/sphinx-dev/-/NaEV510lJroJ.
To post to this group, send email to [email protected].
To unsubscribe from this group, send email to
[email protected].
For more options, visit this group at
http://groups.google.com/group/sphinx-dev?hl=en.
#! /usr/bin/python
# A small script, which checks Sphinx reStructured Text (.rst) files for various inconsistencies and errors so as to save
# bandwidth by catching some of the most obvious problems before the document is sent off for review.
import glob
import sys
class RestructuredTextChecker:
def __init__(self):
pass
def load(self, filename, stderr=sys.stdout):
stream = open(filename, "rt")
number = 0 # line number
last = "" # last/previous line
while 1:
# read yet another line
line = stream.readline()
# if None, we're at the end of the input
if not line:
break
# increment line number
number += 1
# drop trailing newline, if any
if line[-1] == '\n':
line = line[:-1]
# check for trailing whitespace
if line.rstrip() != line:
stderr.write("(%s %d) Warning: Trailing whitespace detected\n" % ( filename, number ))
line = line.rstrip() # make comparisons of marker text possible
# check for too short or too long section marker
if len(line) > 0 and line[0] in "=-^":
if last != "" and len(line) < len(last):
stderr.write("(%s %d) Warning: Marker line too short\n" % ( filename, number ))
elif last != "" and len(line) > len(last):
stderr.write("(%s %d) Warning: Marker line too long\n" % ( filename, number ))
last = "" # disable line-too-long check of section headers
continue
# check for too long lines (in excess of 79 characters)
if len(last) > 79:
stderr.write("(%s %d) Warning: Line exceeds 79 characters\n" % ( filename, number - 1 ))
# todo: add other checks as they are discovered and deemed usable
# save this line for possible future marker comparison
last = line
stream.close()
def main(args):
# redirect all output to stdout (stderr belongs to the `yes` family of utterly insane inventions).
output = sys.stdout
# if no args given, show help
if len(args) == 0:
output.write("reStructured Text Checker v0.03\n")
output.write("Copyright (C) 2012 The LLVM Team. All Rights Reserved.\n")
output.write("\n")
output.write("Syntax: \"chkrst\" source-file(s)\n")
output.write("\n")
output.write("Scans and checks .rst files for obvious yet embarrassing errors.\n")
return 0
# expand wildcards in arguments
files = []
for arg in args:
found = glob.glob(arg)
if found == []:
output.write("Warning: Pattern '%s' not matched\n" % arg)
files += found
# process each file in turn
for file in files:
checker = RestructuredTextChecker()
checker.load(file, output)
del checker
return 0
if __name__ == "__main__":
result = main(sys.argv[1:])
sys.exit(result)
