[Git][ghc/ghc][wip/docs-errors] Make the build more strict on documentation errors

[Krzysztof Gogolewski (@monoidal)]

Krzysztof Gogolewski pushed to branch wip/docs-errors at Glasgow Haskell Compiler / GHC


Commits:
a6df5d7b by Krzysztof Gogolewski at 2024-01-13T19:13:08+01:00
Make the build more strict on documentation errors

* Detect undefined labels. This can be tested by adding :ref:`nonexistent`
  to a documentation rst file; attempting to build docs will fail.
* Detect errors. While we have plenty of warnings, we can at least enforce
  that Sphinx does not report errors.
  I have fixed the only remaining error, in `required_type_arguments.rst`.

Unrelated change: I have documented that the `-dlint` enables
`-fcatch-nonexhaustive-cases`, as can be verified by checking
`enableDLint`.

- - - - -


3 changed files:

- docs/users_guide/debugging.rst
- docs/users_guide/exts/required_type_arguments.rst
- hadrian/src/Rules/Documentation.hs


Changes:

=====================================
docs/users_guide/debugging.rst
=====================================
@@ -1046,7 +1046,7 @@ Checking for consistency
     :shortdesc: Enable several common internal sanity checkers
     :type: dynamic
 
-    :implies: -dcore-lint, -dstg-lint, -dcmm-lint, -dasm-lint, -fllvm-fill-undef-with-garbage, -debug
+    :implies: -dcore-lint, -dstg-lint, -dcmm-lint, -dasm-lint, -fllvm-fill-undef-with-garbage, -fcatch-nonexhaustive-cases, -debug
     :since: 9.4.1
 
     Turn on various heavy-weight intra-pass sanity-checking measures within GHC


=====================================
docs/users_guide/exts/required_type_arguments.rst
=====================================
@@ -281,8 +281,8 @@ to bind type variables::
   const :: a -> b -> a               -- implicit quantification
   const :: forall a b. a -> b -> a   -- explicit quantification
 
-Normally, implicit quantification is unaffected by term variables in scope:
-::
+Normally, implicit quantification is unaffected by term variables in scope: ::
+
   f a = ...  -- the LHS binds `a`
     where const :: a -> b -> a
              -- implicit quantification over `a` takes place


=====================================
hadrian/src/Rules/Documentation.hs
=====================================
@@ -168,6 +168,12 @@ checkSphinxWarnings out = do
     when ("reference target not found" `isInfixOf` log)
       $ fail "Undefined reference targets found in Sphinx log."
 
+    when ("undefined label:" `isInfixOf` log)
+      $ fail "Undefined labels found in Sphinx log."
+
+    when ("ERROR:" `isInfixOf` log)
+      $ fail "Errors found in the Sphinx log."
+
 -- | Check that all GHC flags are documented in the users guide.
 checkUserGuideFlags :: FilePath -> Action ()
 checkUserGuideFlags documentedFlagList = do



View it on GitLab: https://gitlab.haskell.org/ghc/ghc/-/commit/a6df5d7bf0c0557d10a460bf572f80a6065b5f6a

-- 
View it on GitLab: https://gitlab.haskell.org/ghc/ghc/-/commit/a6df5d7bf0c0557d10a460bf572f80a6065b5f6a
You're receiving this email because of your account on gitlab.haskell.org.


-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.haskell.org/pipermail/ghc-commits/attachments/20240113/e43bf88c/attachment-0001.html>