diff options
author | Ben Gamari <ben@smart-cactus.org> | 2019-10-06 15:06:01 -0400 |
---|---|---|
committer | Marge Bot <ben+marge-bot@smart-cactus.org> | 2019-10-08 05:12:58 -0400 |
commit | 98c094227c7738a65dfc5908b3397d7275e56ea1 (patch) | |
tree | 65f27374fa2a9c89142c48426615d42c8c2da475 | |
parent | ca4791dba46b0c285763d3dd76a9c8a61b279a35 (diff) | |
download | haskell-98c094227c7738a65dfc5908b3397d7275e56ea1.tar.gz |
users-guide: Run sphinx in nit-picky mode
This ensure that it blurts an error on missing references.
-rw-r--r-- | docs/users_guide/conf.py | 23 | ||||
-rw-r--r-- | hadrian/src/Hadrian/Builder/Sphinx.hs | 2 | ||||
-rw-r--r-- | hadrian/src/Rules/Documentation.hs | 14 | ||||
-rw-r--r-- | rules/sphinx.mk | 4 | ||||
m--------- | utils/haddock | 0 |
5 files changed, 41 insertions, 2 deletions
diff --git a/docs/users_guide/conf.py b/docs/users_guide/conf.py index 1f6f8b5b11..597d6765c7 100644 --- a/docs/users_guide/conf.py +++ b/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) diff --git a/hadrian/src/Hadrian/Builder/Sphinx.hs b/hadrian/src/Hadrian/Builder/Sphinx.hs index 7e2401d0d5..07bd941fe7 100644 --- a/hadrian/src/Hadrian/Builder/Sphinx.hs +++ b/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 diff --git a/hadrian/src/Rules/Documentation.hs b/hadrian/src/Rules/Documentation.hs index 1326cb5a89..2671c921e2 100644 --- a/hadrian/src/Rules/Documentation.hs +++ b/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. diff --git a/rules/sphinx.mk b/rules/sphinx.mk index 43dff6177b..15e7152a12 100644 --- a/rules/sphinx.mk +++ b/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 diff --git a/utils/haddock b/utils/haddock -Subproject 58933236f116a26a2827b0cb5c46947e4f056c7 +Subproject a7c42a29f7c33f5fdbb04acc3866ec907c2e00f |