Reorder doc/spelling build order and improve spelling error message f…

…or CI (apache#14196)

Generic Sphinx errors that were unrelated to spelling were being raised as spelling errors leading to potential confusion. Reversing the order of the build (i.e. running the docs build before the spelling build) will catch such errors and more appropriately denote the issue as a build issue and not a spelling issue. Additionally, the error message for Sphinx errors unrelated to spelling has been updated to be more clear for such cases.

closes: apache#14051

docs/build_docs.py

@@ -139,18 +139,18 @@ def build_docs_for_packages(
         print("#" * 20, f"[{package_no}/{len(current_packages)}] {package_name}", "#" * 20)
         builder = AirflowDocsBuilder(package_name=package_name, for_production=for_production)
         builder.clean_files()
-        if not docs_only:
-            with with_group(f"Check spelling: {package_name}"):
-                spelling_errors = builder.check_spelling(verbose=verbose)
-            if spelling_errors:
-                all_spelling_errors[package_name].extend(spelling_errors)
-
         if not spellcheck_only:
             with with_group(f"Building docs: {package_name}"):
                 docs_errors = builder.build_sphinx_docs(verbose=verbose)
             if docs_errors:
                 all_build_errors[package_name].extend(docs_errors)
 
+        if not docs_only:
+            with with_group(f"Check spelling: {package_name}"):
+                spelling_errors = builder.check_spelling(verbose=verbose)
+            if spelling_errors:
+                all_spelling_errors[package_name].extend(spelling_errors)
+
     return all_build_errors, all_spelling_errors
 
 

docs/exts/docs_build/spelling_checks.py

@@ -146,10 +146,14 @@ def display_spelling_error_summary(spelling_errors: Dict[str, List[SpellingError
     print("=" * 50)
     print()
     msg = """
-If the spelling is correct, add the spelling to docs/spelling_wordlist.txt
-or use the spelling directive.
+If there are spelling errors in the summary above, and the spelling is
+correct, add the spelling to docs/spelling_wordlist.txt or use the
+spelling directive.
 Check https://sphinxcontrib-spelling.readthedocs.io/en/latest/customize.html#private-dictionaries
 for more details.
+
+If there are no spelling errors in the summary above, there might be an
+issue unrelated to spelling. Please review the traceback.
     """
     print(msg)
     print()

docs/spelling_wordlist.txt

@@ -1388,6 +1388,7 @@ webpage
 webserver
 webservers
 webservice
+werkzeug
 whitespace
 whl
 winrm