[Git][NTPsec/ntpsec][master] 3 commits: First cut at link-checking tool for the documentation.

[Eric S. Raymond]

Eric S. Raymond pushed to branch master at NTPsec / ntpsec


Commits:
e28d8a07 by Eric S. Raymond at 2016-11-29T13:15:22-05:00
First cut at link-checking tool for the documentation.

- - - - -
e57947b5 by Eric S. Raymond at 2016-11-29T14:10:45-05:00
Improved anchot detection in linkcheck.

- - - - -
4d905a3e by Eric S. Raymond at 2016-11-29T15:57:30-05:00
The link checker is working.

As a demonstration, this commit includes one fix for a glitch found using it.

- - - - -


3 changed files:

- + devel/linkcheck
- docs/includes/misc-options.txt
- wscript


Changes:

=====================================
devel/linkcheck
=====================================
--- /dev/null
+++ b/devel/linkcheck
@@ -0,0 +1,76 @@
+#!/usr/bin/env python
+#
+# linkcheck - check link integrity in the document tree
+#
+# Run this script from docs/
+#
+# SPDX-License-Identifier: BSD-2-clause
+from __future__ import print_function, division
+
+import os, re
+
+boxanchor_re = re.compile(r"\[\[([a-z0-9_-]*)\]\]")
+linkanchor_re = re.compile(r"anchor:([a-z0-9_-]*)\[\]")
+refanchor_re = re.compile(r"link:([^.]*).html#([a-z0-9_-]*)")
+
+prefix = "docs/"
+
+def tabulate(path):
+    iostack.append((0, open(path)))
+    linecount = 0
+    while True:
+        line = iostack[-1][1].readline()
+        linecount += 1
+        if line == "":
+            iostack[-1][1].close()
+            (linecount, _) = iostack.pop()
+            if not iostack:
+                return
+            else:
+                continue
+        if line.startswith("include::"):
+            filestem = line.strip()[9:][:-2]
+            iostack.append((linecount, open(os.path.join(prefix, filestem))))
+            continue
+        # Ordinary processing 
+        # This is the tricky part. Because we're reference-checking the
+        # generated HTML, the file part of a stored anchor name needs to be
+        # the original path from the top of the include stack, not
+        # whatever inclusion we might be walking through now.
+        html = path[len(prefix):].replace(".txt", ".html") 
+        m = boxanchor_re.search(line)
+        if m:
+            anchor = "link:" + html + "#" + m.group(1)
+            anchors.add(anchor)
+        m = linkanchor_re.search(line)
+        if m:
+            anchor = "link:" + html + "#" + m.group(1)
+            anchors.add(anchor)
+        m = refanchor_re.search(line)
+        if m:
+            references[m.group(0)] = (iostack[-1][1].name, linecount)
+
+if __name__ == '__main__':
+    iostack = []
+    references = {}
+    anchors = set([])
+    for dirpath, dnames, fnames in os.walk(prefix):
+        for f in fnames:
+            fullpath = os.path.join(dirpath, f)
+            if fullpath.endswith(".txt") and not "includes" in fullpath:
+                tabulate(fullpath)
+    #print("References: %s" % references)
+    #print("Anchors: %s" % anchors)
+    hanging = []
+    for ref in references:
+        if ref not in anchors:
+            hanging.append(ref)
+    print("%d anchors, %d references, %d references unsatisfied" % \
+          (len(anchors), len(references), len(hanging)))
+    unsatisfied = list(hanging)
+    unsatisfied.sort()
+    for item in unsatisfied:
+        print('"%s", line %d: %s' % \
+              (references[item][0], references[item][1], item))
+
+# end


=====================================
docs/includes/misc-options.txt
=====================================
--- a/docs/includes/misc-options.txt
+++ b/docs/includes/misc-options.txt
@@ -218,6 +218,7 @@ and so on is suppressed.
   peer variables and the +clock_var_list+ holds the names of the reference
   clock variables.
 
+[[tinker]]
 +tinker+ [+allan+ _allan_ | +dispersion+ _dispersion_ | +freq+ _freq_ | +huffpuff+ _huffpuff_ | +panic+ _panic_ | +step+ _step_ | +stepback+ _stepback_ | +stepfwd+ _stepfwd_ | +stepout+ _stepout_]::
   This command can be used to alter several system variables in very
   exceptional circumstances. It should occur in the configuration file


=====================================
wscript
=====================================
--- a/wscript
+++ b/wscript
@@ -257,6 +257,10 @@ def cxfreeze(ctx):
     "Create standalone binaries from Python scripts."
     ctx.exec_command("for prog in " + " ".join(python_scripts) + "; do cxfreeze $prog; done")
 
+def linkcheck(ctx):
+    "Report references without anchors in the documentation."
+    ctx.exec_command("devel/linkcheck")
+
 # The following sets edit modes for GNU EMACS
 # Local Variables:
 # mode:python



View it on GitLab: https://gitlab.com/NTPsec/ntpsec/compare/d3494e906048a8e5882be0f63b44a6093c01105f...4d905a3eb24fd4f0f58af8e34d8a842ca5620c78
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.ntpsec.org/pipermail/vc/attachments/20161129/0fab28c5/attachment.html>