Print correct order for include order/style issues

Make the 'check-source' target print the correct/conforming include
order together with the "include order/style is not consistent" message,
and add a reference to related documentation.  This hopefully makes
these messages easier to understand.

Change-Id: I63c4defaefab273cce399cc77522ed69c428de12

diff --git a/docs/doxygen/check-source.py b/docs/doxygen/check-source.py
index 0856fb2a7de8b8cac69c45fcab351abd9caf996f..8295a6e5536b6474b5735173bfc7cc82d23cae3b 100755 (executable)
--- a/docs/doxygen/check-source.py
+++ b/docs/doxygen/check-source.py
@@ -148,12 +148,6 @@ def check_include(fileobj, includedfile, reporter):
     if not otherfile:
         reporter.code_issue(includedfile,
                 "includes non-local file as {0}".format(includedfile))
-    # TODO: Reinstantiate a check once there is clarity on what we want
-    # to enforce.
-    #elif fileobj.is_installed() and not includedfile.is_relative():
-    #    reporter.code_issue(includedfile,
-    #            "installed header includes {0} using non-relative path"
-    #            .format(includedfile))
     if not otherfile:
         return
     if fileobj.is_installed() and not otherfile.is_installed():
@@ -360,9 +354,12 @@ def check_all(tree, reporter, check_ignored):
         check_file(fileobj, reporter)
         for includedfile in fileobj.get_includes():
             check_include(fileobj, includedfile, reporter)
-        if fileobj.should_includes_be_sorted() \
-                and not includesorter.check_sorted(fileobj):
-            reporter.code_issue(fileobj, "include style/order is not consistent")
+        if fileobj.should_includes_be_sorted():
+            is_sorted, details = includesorter.check_sorted(fileobj)
+            if not is_sorted:
+                details.append("You can use includesorter.py to do the sorting automatically; see docs/dev-manual/gmxtree.rst")
+                reporter.code_issue(fileobj,
+                        "include style/order is not consistent; see docs/dev-manual/includestyle.rst", details)
 
     for classobj in tree.get_classes():
         check_class(classobj, reporter)

diff --git a/docs/doxygen/includesorter.py b/docs/doxygen/includesorter.py
index 7e07864c80ba855544c92fdebd05711ea0db99da..9c7da69f10a0f9a054f5257cce0c0990722204c7 100755 (executable)
--- a/docs/doxygen/includesorter.py
+++ b/docs/doxygen/includesorter.py
@@ -300,10 +300,20 @@ class IncludeSorter(object):
         """Check that includes within a file are sorted."""
         # TODO: Make the checking work without full contents of the file
         lines = fileobj.get_contents()
-        self._changed = False
+        is_sorted = True
+        details = None
         for block in fileobj.get_include_blocks():
-            self._sort_include_block(block, lines)
-        return not self._changed
+            self._changed = False
+            sorted_lines = self._sort_include_block(block, lines)
+            if self._changed:
+                is_sorted = False
+                # TODO: Do a proper diff to show the actual changes.
+                if details is None:
+                    details = ["Correct order/style is:"]
+                else:
+                    details.append("    ...")
+                details.extend(["    " + x.rstrip() for x in sorted_lines])
+        return (is_sorted, details)
 
 def main():
     """Run the include sorter script."""