users-guide: Run sphinx in nit-picky mode

This ensure that it blurts an error on missing references.

docs/users_guide/conf.py

@@ -24,6 +24,29 @@ source_suffix = '.rst'
 source_encoding = 'utf-8-sig'
 master_doc = 'index'
 
+nitpick_ignore = [
+    ("envvar", "EDITOR"),
+    ("envvar", "HOME"),
+    ("envvar", "LD_LIBRARY_PATH"),
+    ("envvar", "LIBRARY_PATH"),
+    ("envvar", "PATH"),
+    ("envvar", "RPATH"),
+    ("envvar", "RUNPATH"),
+    ("envvar", "TMPDIR"),
+
+    ("c:type", "bool"),
+
+    # See #17314
+    ("ghc-flag", "-pgmo ⟨port⟩"),
+    ("ghc-flag", "-pgmo ⟨option⟩"),
+
+    ("extension", "DoAndIfThenElse"),
+    ("extension", "RelaxedPolyRec"),
+
+    # See #16629
+    ("extension", "UnliftedFFITypes"),
+]
+
 rst_prolog = """
 .. |llvm-version| replace:: {llvm_version}
 """.format(llvm_version=ghc_config.llvm_version)

hadrian/src/Hadrian/Builder/Sphinx.hs

@@ -30,6 +30,8 @@ args mode = do
     outPath <- getOutput
     mconcat [ arg "-b", arg modeString
             , arg "-d", arg $ outPath -/- (".doctrees-" ++ modeString)
+            , arg "-n" -- nit-picky mode to ensure missing references are caught
+            , arg "-w", arg $ outPath -/- ".log" -- dump warnings to log file
             , arg =<< getInput
             , arg outPath ]
   where

hadrian/src/Rules/Documentation.hs

@@ -114,6 +114,16 @@ documentationRules = do
     where archiveTarget "libraries"   = Haddocks
           archiveTarget _             = SphinxHTML
 
+-- | Check Sphinx log for undefined reference target errors. Ideally we would
+-- use sphinx's @-W@ flag here but unfortunately it also turns syntax
+-- highlighting warnings into errors which is undesirable.
+checkSphinxWarnings :: FilePath  -- ^ output directory
+                    -> Action ()
+checkSphinxWarnings out = do
+    log <- liftIO $ readFile (out -/- ".log")
+    when ("reference target not found" `isInfixOf` log)
+      $ fail "Undefined reference targets found in Sphinx log."
+
 
 ------------------------------------- HTML -------------------------------------
 
@@ -147,6 +157,7 @@ buildSphinxHtml path = do
         rstFiles <- getDirectoryFiles rstFilesDir ["**/*.rst"]
         need (map (rstFilesDir -/-) rstFiles)
         build $ target docContext (Sphinx Html) [pathPath path] [dest]
+        checkSphinxWarnings dest
 
 ------------------------------------ Haddock -----------------------------------
 
@@ -259,6 +270,7 @@ buildSphinxPdf path = do
             rstFiles <- getDirectoryFiles rstFilesDir ["**/*.rst"]
             need (map (rstFilesDir -/-) rstFiles)
             build $ target docContext (Sphinx Latex) [pathPath path] [dir]
+            checkSphinxWarnings dir
             build $ target docContext Xelatex [path <.> "tex"] [dir]
             copyFileUntracked (dir -/- path <.> "pdf") file
 
@@ -275,6 +287,7 @@ buildSphinxInfoGuide = do
             rstFiles <- getDirectoryFiles rstFilesDir ["**/*.rst"]
             need (map (rstFilesDir -/-) rstFiles)
             build $ target docContext (Sphinx Info) [pathPath path] [dir]
+            checkSphinxWarnings dir
             -- Sphinx outputs texinfo source and a makefile, the
             -- default target of which actually produces the target
             -- for this build rule.
@@ -306,6 +319,7 @@ buildManPage = do
         need ["docs/users_guide/ghc.rst"]
         withTempDir $ \dir -> do
             build $ target docContext (Sphinx Man) ["docs/users_guide"] [dir]
+            checkSphinxWarnings dir
             copyFileUntracked (dir -/- "ghc.1") file
 
 -- | Find the Haddock files for the dependencies of the current library.

rules/sphinx.mk

@@ -40,7 +40,7 @@ html : html_$1
 
 ifneq "$$(BINDIST)" "YES"
 $1/build-html/$2/index.html: $1/conf.py $$($1_RST_SOURCES)
-	$(SPHINXBUILD) -b html -d $1/.doctrees-html $(SPHINXOPTS) $1 $1/build-html/$2
+	$(SPHINXBUILD) -b html -d $1/.doctrees-html -w $1/.log -n $(SPHINXOPTS) $1 $1/build-html/$2
 endif
 
 
@@ -62,7 +62,7 @@ ifneq "$$(BINDIST)" "YES"
 # besides the last to fail.
 
 $1/$2.pdf: $1/conf.py $$($1_RST_SOURCES)
-	$(SPHINXBUILD) -b latex -d $1/.doctrees-pdf $(SPHINXOPTS) $1 $1/build-pdf/$2
+	$(SPHINXBUILD) -b latex -d $1/.doctrees-pdf -w $1/.log -n $(SPHINXOPTS) $1 $1/build-pdf/$2
 	cd $1/build-pdf/$2 ; xelatex -halt-on-error $2.tex 2>/dev/null >/dev/null || true
 	cd $1/build-pdf/$2 ; xelatex -halt-on-error $2.tex 2>/dev/null >/dev/null || true
 	cd $1/build-pdf/$2 ; xelatex -halt-on-error $2.tex 2>/dev/null >/dev/null || true

haddock @ a7c42a29

-Subproject commit 58933236f116a26a2827b0cb5c46947e4f056c77
+Subproject commit a7c42a29f7c33f5fdbb04acc3866ec907c2e00f3