[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:
445f6460 by Krzysztof Gogolewski at 2024-01-13T20:44:29+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.
  Fixed the undefined label in `9.8.1-notes.rst`.
* Detect errors. While we have plenty of warnings, we can at least enforce
  that Sphinx does not report errors.
  Fixed the 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`.

- - - - -


4 changed files:

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


Changes:

=====================================
docs/users_guide/9.8.1-notes.rst
=====================================
@@ -256,7 +256,7 @@ Runtime system
 - The extensions fields of constructors of ``IE`` now take ``Maybe (WarningTxt p)``
   in ``GhcPs`` and ``GhcRn`` variants of the Syntax Tree.
   This represents the warning assigned to a certain export item,
-  which is used for :ref:`deprecated-exports`.
+  which is used for deprecated exports (see :ref:`warning-deprecated-pragma`).
 
 ``ghc-heap`` library
 ~~~~~~~~~~~~~~~~~~~~


=====================================
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/445f646003dff5d57a0ca73f5f7afe6373554685

-- 
View it on GitLab: https://gitlab.haskell.org/ghc/ghc/-/commit/445f646003dff5d57a0ca73f5f7afe6373554685
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/56a6aa91/attachment-0001.html>