[Git][ghc/ghc][wip/docs-fixes] 2 commits: docs: Fix various documentation issues

Ben Gamari gitlab at gitlab.haskell.org
Thu Sep 17 14:56:09 UTC 2020 


Ben Gamari pushed to branch wip/docs-fixes at Glasgow Haskell Compiler / GHC


Commits:
a14b8644 by Ben Gamari at 2020-09-17T10:54:53-04:00
docs: Fix various documentation issues

- - - - -
1222d3fe by Ben Gamari at 2020-09-17T10:55:00-04:00
hadrian: Fail on Sphinx syntax errors

Specifically the "Inline literal start-string without end-string"
warning, which typically means that the user neglected to separate
an inline code block from suffix text with a backslash.

- - - - -


6 changed files:

- docs/users_guide/9.0.1-notes.rst
- docs/users_guide/exts/explicit_forall.rst
- docs/users_guide/exts/instances.rst
- docs/users_guide/release-notes.rst
- docs/users_guide/runtime_control.rst
- hadrian/src/Rules/Documentation.hs


Changes:

=====================================
docs/users_guide/9.0.1-notes.rst
=====================================
@@ -49,9 +49,10 @@ Highlights
 
   - GHC now relies on a new "ghc-bignum" package to provide Integer/Natural
     implementations. This package supports the following backends:
-      - gmp: adapted from integer-gmp package that was used before
-      - native: new Haskell implementation, faster than integer-simple which is
-        not used anymore
+
+    - gmp: adapted from integer-gmp package that was used before
+    - native: new Haskell implementation, faster than integer-simple which is
+      not used anymore
 
   - All backends now use the same representation for big numbers (the one that
     was previously used only by integer-gmp). It led to several compiler


=====================================
docs/users_guide/exts/explicit_forall.rst
=====================================
@@ -37,9 +37,9 @@ Notes:
 
       instance forall a. Eq a => Eq [a] where ...
 
-  Note that the use of ``forall``s in instance declarations is somewhat
+  Note that the use of ``forall``\s in instance declarations is somewhat
   restricted in comparison to other types. For example, instance declarations
-  are not allowed to contain nested ``forall``s. See
+  are not allowed to contain nested ``forall``\s. See
   :ref:`formal-instance-syntax` for more information.
 
 - If the :ghc-flag:`-Wunused-foralls` flag is enabled, a warning will be emitted


=====================================
docs/users_guide/exts/instances.rst
=====================================
@@ -141,22 +141,22 @@ Where:
 
 - ``btype`` is a type that is not allowed to have an outermost
   ``forall``/``=>`` unless it is surrounded by parentheses. For example,
-  ``forall a. a`` and ``Eq a => a`` are not legal ``btype``s, but
+  ``forall a. a`` and ``Eq a => a`` are not legal ``btype``\s, but
   ``(forall a. a)`` and ``(Eq a => a)`` are legal.
 - ``ctype`` is a ``btype`` that has no restrictions on an outermost
-  ``forall``/``=>``, so ``forall a. a`` and ``Eq a => a`` are legal ``ctype``s.
-- ``arg_type`` is a type that is not allowed to have ``forall``s or ``=>``s
+  ``forall``/``=>``, so ``forall a. a`` and ``Eq a => a`` are legal ``ctype``\s.
+- ``arg_type`` is a type that is not allowed to have ``forall``s or ``=>``\s
 - ``prefix_cls_tycon`` is a class type constructor written prefix (e.g.,
   ``Show`` or ``(&&&)``), while ``infix_cls_tycon`` is a class type constructor
-  written infix (e.g., ```Show``` or ``&&&``).
+  written infix (e.g., ``\`Show\``` or ``&&&``).
 
 This is a simplified grammar that does not fully delve into all of the
 implementation details of GHC's parser (such as the placement of Haddock
 comments), but it is sufficient to attain an understanding of what is
 syntactically allowed. Some further various observations about this grammar:
 
-- Instance declarations are not allowed to be declared with nested ``forall``s
-  or ``=>``s. For example, this would be rejected: ::
+- Instance declarations are not allowed to be declared with nested ``forall``\s
+  or ``=>``\s. For example, this would be rejected: ::
 
     instance forall a. forall b. C (Either a b) where ...
 


=====================================
docs/users_guide/release-notes.rst
=====================================
@@ -5,3 +5,4 @@ Release notes
    :maxdepth: 1
 
    9.0.1-notes
+   9.2.1-notes


=====================================
docs/users_guide/runtime_control.rst
=====================================
@@ -183,6 +183,13 @@ Event log output
 Furthermore GHC lets you specify the way event log data (see :rts-flag:`-l
 ⟨flags⟩`) is written through a custom :c:type:`EventLogWriter`:
 
+.. The size_t declaration below is simply to ensure that the build doesn't fail with an
+   undefined reference target warning as Sphinx doesn't know about size_t.
+
+.. c:type:: size_t
+
+   :hidden:
+
 .. c:type:: EventLogWriter
 
     A sink of event-log data.


=====================================
hadrian/src/Rules/Documentation.hs
=====================================
@@ -127,6 +127,21 @@ checkSphinxWarnings :: FilePath  -- ^ output directory
                     -> Action ()
 checkSphinxWarnings out = do
     log <- liftIO $ readFile (out -/- ".log")
+    when ("Inline literal start-string without end-string." `isInfixOf` log)
+      $ fail $ unlines
+        [ "Syntax error found in Sphinx log. "
+        , ""
+        , "This likely means that you have forgotten a \\ after inline code block. For instance,"
+        , "you might have written:"
+        , ""
+        , "    are not allowed to contain nested ``forall``s."
+        , ""
+        , "Whereas you need to write:"
+        , ""
+        , "    are not allowed to contain nested ``forall``\s."
+        , ""
+        ]
+
     when ("reference target not found" `isInfixOf` log)
       $ fail "Undefined reference targets found in Sphinx log."
 



View it on GitLab: https://gitlab.haskell.org/ghc/ghc/-/compare/195ad0f8e4b84d38bffd1fab2d2b8e925d48c255...1222d3fe435b63988dc5d13c7deb3b211de1225c

-- 
View it on GitLab: https://gitlab.haskell.org/ghc/ghc/-/compare/195ad0f8e4b84d38bffd1fab2d2b8e925d48c255...1222d3fe435b63988dc5d13c7deb3b211de1225c
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/20200917/1500b29f/attachment-0001.html>

More information about the ghc-commits mailing list