Updated docs linter for scripts

Also made scripts toctree more explicit
develop
PeridexisErrant 2015-10-24 17:00:54 +11:00
parent ddae19ad8b
commit 54f3c6a138
2 changed files with 48 additions and 27 deletions

@ -48,10 +48,13 @@ The following pages document all the standard DFHack scripts.
.. toctree:: .. toctree::
:glob:
:maxdepth: 2 :maxdepth: 2
/docs/_auto/* /docs/_auto/base
/docs/_auto/devel
/docs/_auto/fix
/docs/_auto/gui
/docs/_auto/modtools
.. warning:: .. warning::
@ -66,5 +69,5 @@ The following pages document all the standard DFHack scripts.
:glob: :glob:
:maxdepth: 2 :maxdepth: 2
/scripts/3rdparty/*/* /scripts/3rdparty/*/README

@ -1,30 +1,48 @@
import os, sys from io import open
import os
import sys
scriptdir = 'scripts' scriptdirs = (
'scripts',
#'scripts/devel', # devel scripts don't have to be documented
'scripts/fix',
'scripts/gui',
'scripts/modtools')
def check_file(fname):
doclines = []
with open(fname, errors='ignore') as f:
for l in f.readlines():
if doclines or l.strip().endswith('=begin'):
doclines.append(l.rstrip())
if l.startswith('=end'):
break
else:
#print(doclines); sys.exit()
print('Error: docs start but not end:', fname)
return 1
title, underline = doclines[2], doclines[3]
if underline != '=' * len(title):
print('Error: title/underline mismatch:', fname, title, underline)
return 1
start = fname.split('/')[-2]
if start != 'scripts' and not title.startswith(start):
print('Error: title is missing start string:', fname, start, title)
return 1
return 0
def is_script(fname):
if not os.path.isfile(fname):
return False
return fname.endswith('.lua') or fname.endswith('.rb')
def main(): def main():
files = [] """Check that all DFHack scripts include documentation (not 3rdparty)"""
for item in os.listdir(scriptdir): errors = 0
path = os.path.join(scriptdir, item) for path in scriptdirs:
if is_script(path): for f in os.listdir(path):
files.append(item) f = path + '/' + f
elif os.path.isdir(path) and item not in ('devel', '3rdparty'): if os.path.isfile(f) and f[-3:] in {'.rb', 'lua'}:
files.extend([item + '/' + f for f in os.listdir(path) errors += check_file(f)
if is_script(os.path.join(path, f))]) return errors
with open('docs/Scripts.rst') as f:
text = f.read()
error = 0
for f, _ in [os.path.splitext(p) for p in files]:
heading = '\n' + f + '\n' + '=' * len(f) + '\n'
if heading not in text:
print('WARNING: {:28} not documented in docs/Scripts'.format(f))
error = 1
sys.exit(error)
if __name__ == '__main__': if __name__ == '__main__':
main() sys.exit(bool(main()))