Updated docs linter for scripts

Also made scripts toctree more explicit

docs/Scripts.rst

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

travis/script-in-readme.py

@@ -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():
-    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__':
-    main()
+    sys.exit(bool(main()))