Minor improvements to the Python linter (swiftlang#12079)

* Mention utils/python_lint.py in docs/ContinuousIntegration.md

* Improve error messages in utils/python_lint.py

* Make python_lint.py fail if required modules are not found

Previously, it returned 0 in such a case, which is considered as a
successful exit.

* Continue returning success when missing modules [python_lint.py]

Reverts ffd3b78

Author: mnvr

docs/ContinuousIntegration.md

@@ -8,7 +8,7 @@
     - [@swift-ci](#swift-ci)
     - [Smoke Testing](#smoke-testing)
     - [Validation Testing](#validation-testing)
-    - [Lint Testing](#lint-testing)
+    - [Linting](#linting)
     - [Specific Preset Testing](#specific-preset-testing)
 - [Cross Repository Testing](#cross-repository-testing)
 - [ci.swift.org bots](#ciswiftorg-bots)
@@ -28,7 +28,7 @@ Users with [commit access](https://swift.org/contributing/#commit-access) can tr
 1. Smoke Testing
 2. Validation Testing
 3. Benchmarking.
-4. Lint Testing
+4. Linting
 5. Source Compatibility Testing
 6. Specific Preset Testing
 
@@ -121,11 +121,11 @@ Platform        | Comment | Check Status
 macOS platform  | @swift-ci Please benchmark       | Swift Benchmark on OS X Platform (many runs - rigorous)
 macOS platform  | @swift-ci Please smoke benchmark | Swift Benchmark on OS X Platform (few runs - sanity)
 
-### Lint Testing
+### Linting
 
-Language     | Comment | Check Status
------------- | ------- | ------------
-Python       | @swift-ci Please Python lint | Python lint
+Language     | Comment | What it Does | Corresponding Local Command
+------------ | ------- | ------------ | -------------
+Python       | @swift-ci Please Python lint | Lints Python sources | `./utils/python_lint.py`
 
 ### Source Compatibility Testing
 

utils/python_lint.py

@@ -23,8 +23,22 @@ def lint(arguments, verbose=True):
     )
     if flake8_result != 0:
         if verbose:
-            print("Missing modules flake8 or flake8-import-order. Please be"
-                  " sure to install these python packages before linting.")
+            print("""
+The flake8 and flake8-import-order Python packages are required for linting,
+but these were not found on your system.
+
+You can install these using:
+
+    python -m pip install flake8
+    python -m pip install flake8-import-order
+
+For more help, see http://flake8.pycqa.org.""")
+
+        # We should be returning `flake8_result` from here.  However,
+        # some Python files lint themselves using embedded doctests,
+        # which causes CI smoke tests to fail because the Linux nodes
+        # do not have these modules installed.
+
         return 0
 
     utils_directory = os.path.dirname(os.path.abspath(__file__))