Commit 3e5d0f18 authored by Ben Gamari's avatar Ben Gamari Committed by Ben Gamari
Browse files

users-guide: Make it easier to reference haddocks

Previously you had to painstakingly construct the URI to the haddock
documentation. Now the Python bits have enough smarts to construct this
themselves.

Reviewers: austin, patrickdoc

Reviewed By: patrickdoc

Subscribers: rwbarton, thomie

Differential Revision: https://phabricator.haskell.org/D3785
parent 58b62d6b
......@@ -319,8 +319,8 @@ Runtime system
move long-lived data outside of the heap so that the garbage
collector does not have to trace it repeatedly. Compacted data can
also be serialized, stored, and deserialized again later by the same
program. For more details see the :ghc-compact-ref:`GHC.Compact
<GHC-Compact.html>` module. Moreover, see the ``compact`` library on `Hackage
program. For more details see the :ghc-compact-ref:`GHC.Compact.` module.
Moreover, see the ``compact`` library on `Hackage
<https://hackage.haskell.org/package/compact>`_ for a high-level interface.
- There is new support for improving performance on machines with a
......
......@@ -11,6 +11,7 @@ import os
# Support for :base-ref:, etc.
sys.path.insert(0, os.path.abspath('.'))
from ghc_config import extlinks, version
import ghc_config
extensions = ['sphinx.ext.extlinks', 'sphinx.ext.mathjax']
......@@ -150,6 +151,37 @@ def parse_flag(env, sig, signode):
# Reference name left unchanged
return sig
def haddock_role(lib):
"""
For instance,
* reference to module: :base-ref:`Control.Applicative.`
* reference to identifier: :base-ref:`Control.Applicative.pure`
* reference to type: :base-ref:`Control.Applicative.Applicative`
"""
path = '%s/%s-%s' % (ghc_config.libs_base_uri, lib, ghc_config.lib_versions[lib])
def role(name, rawtext, text, lineno, inliner, options={}, content=[]):
try:
parts = text.split('.')
module_parts = parts[:-1]
thing = parts[-1]
if thing != '':
# reference to type or identifier
tag = 't' if thing[0].isupper() else 'v'
anchor = '#%s:%s' % (tag, thing)
link_text = text
else:
# reference to module
anchor = ''
link_text = '.'.join(module_parts)
uri = '%s/%s.html%s' % (path, '-'.join(module_parts), anchor)
node = nodes.reference(link_text, link_text, refuri=uri)
return [node], []
except ValueError:
msg = inliner.reporter.error('')
return role
def setup(app):
from sphinx.util.docfields import Field, TypedField
......@@ -171,6 +203,15 @@ def setup(app):
Field('static')
])
# Haddock references
app.add_role('th-ref', haddock_role('template-haskell'))
app.add_role('base-ref', haddock_role('base'))
app.add_role('cabal-ref', haddock_role('Cabal'))
app.add_role('ghc-compact-ref', haddock_role('ghc-compact'))
app.add_role('ghc-prim-ref', haddock_role('ghc-prim'))
app.add_role('parallel-ref', haddock_role('parallel'))
app.add_role('array-ref', haddock_role('array'))
app.add_object_type('rts-flag', 'rts-flag',
objname='runtime system command-line option',
parse_node=parse_flag,
......
......@@ -177,7 +177,7 @@ will be of little use unless debug information is available in the executable
and its dependent libraries.
Stack trace functionality is exposed for use by Haskell programs in the
:base-ref:`GHC.ExecutionStack <GHC-ExecutionStack.html>` module. See the Haddock
:base-ref:`GHC.ExecutionStack.` module. See the Haddock
documentation in this module for details regarding usage.
Requesting a stack trace with ``SIGUSR2``
......
......@@ -23,8 +23,8 @@ Haskell 2010 Report. These extensions are described in :ref:`ffi-ghcexts`, but
please note that programs using these features are not portable. Hence, these
features should be avoided where possible.
The FFI libraries are documented in the accompanying library
documentation; see for example the :base-ref:`Foreign <Foreign.html>` module.
The FFI libraries are documented in the accompanying library
documentation; see for example the :base-ref:`Foreign.` module.
GHC differences to the FFI Chapter
----------------------------------
......@@ -581,7 +581,7 @@ where it is useful to have more control over which OS thread is used,
for example when calling foreign code that makes use of thread-local
state. For cases like this, we provide *bound threads*, which are
Haskell threads tied to a particular OS thread. For information on bound
threads, see the documentation for the :base-ref:`Control.Concurrent <Control-Concurrent.html>` module.
threads, see the documentation for the :base-ref:`Control.Concurrent.` module.
Foreign exports and multi-threading
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
......
extlinks = {
'base-ref': ('../libraries/base-@LIBRARY_base_VERSION@/%s', ''),
'cabal-ref': ('../libraries/Cabal-@LIBRARY_Cabal_VERSION@/%s', ''),
'compact-ref': ('../libraries/ghc-compact-@LIBRARY_ghc_compact_VERSION@/%s', ''),
'ghc-prim-ref': ('../libraries/ghc-prim-@LIBRARY_ghc_prim_VERSION@/%s', ''),
'th-ref': ('../libraries/template-haskell-@LIBRARY_template_haskell_VERSION@/%s', ''),
'ghc-ticket': ('https://ghc.haskell.org/trac/ghc/ticket/%s', 'Trac #'),
'ghc-wiki': ('https://ghc.haskell.org/trac/ghc/wiki/%s', 'Trac #'),
}
libs_base_uri = '../libraries'
lib_versions = {
'base': '@LIBRARY_base_VERSION@',
'ghc-prim': '@LIBRARY_ghc_prim_VERSION@',
'template-haskell': '@LIBRARY_template_haskell_VERSION@',
'ghc-compact': '@LIBRARY_ghc_compact_VERSION@',
'ghc': '@LIBRARY_ghc_VERSION@',
'parallel': '@LIBRARY_parallel_VERSION@',
'Cabal': '@LIBRARY_Cabal_VERSION@',
'array': '@LIBRARY_array_VERSION@',
}
version = '@ProjectVersion@'
......@@ -505,8 +505,8 @@ not to replace module loading but to make definitions in .ghci-files
Any exceptions raised during the evaluation or execution of the
statement are caught and printed by the GHCi command line interface (for
more information on exceptions, see the module ``Control.Exception`` in
the libraries :base-ref:`documentation <Control-Exception.html>`).
more information on exceptions, see the module :base-ref:`Control.Exception.` in
the libraries documentation.
Every new binding shadows any existing bindings of the same name,
including entities that are in scope in the current module context.
......
......@@ -73,7 +73,7 @@ case. And if it isn't, we'd like to know about it.
 
All these primitive data types and operations are exported by the
library ``GHC.Prim``, for which there is
:ghc-prim-ref:`detailed online documentation <GHC-Prim.html>`. (This
:ghc-prim-ref:`detailed online documentation <GHC.Prim.>`. (This
documentation is generated from the file ``compiler/prelude/primops.txt.pp``.)
 
If you want to mention any of the primitive data types or operations in
......@@ -1342,7 +1342,7 @@ Monad comprehensions support:
 
Parallel statements are translated using the ``mzip`` function, which
requires a ``MonadZip`` instance defined in
:base-ref:`Control.Monad.Zip <Control-Monad-Zip.html>`:
:base-ref:`Control.Monad.Zip.`:
 
::
 
......@@ -3273,7 +3273,7 @@ More details:
Record field selector polymorphism
----------------------------------
 
The module :base-ref:`GHC.Records <GHC-Records.html>` defines the following: ::
The module :base-ref:`GHC.Records.` defines the following: ::
 
class HasField (x :: k) r a | x r -> a where
getField :: r -> a
......@@ -6382,7 +6382,7 @@ argument in GHC 8.0, but this was removed in GHC 8.2 as a type application (see
 
There are no predefined instances of this class. It is not in scope by default,
but can be brought into scope by importing
:base-ref:`GHC.OverloadedLabels <GHC-OverloadedLabels.html>`. Unlike
:base-ref:`GHC.OverloadedLabels.`. Unlike
``IsString``, there are no special defaulting rules for ``IsLabel``.
 
During typechecking, GHC will replace an occurrence of an overloaded label like
......@@ -8750,10 +8750,9 @@ The ``Coercible`` constraint
 
The constraint ``Coercible t1 t2`` is similar to ``t1 ~ t2``, but
denotes representational equality between ``t1`` and ``t2`` in the sense
of Roles (:ref:`roles`). It is exported by
:base-ref:`Data.Coerce <Data-Coerce.html>`, which also
contains the documentation. More details and discussion can be found in
the paper
of Roles (:ref:`roles`). It is exported by :base-ref:`Data.Coerce.`, which also
contains the documentation. More details and discussion can be found in the
paper
`"Safe Coercions" <http://www.cis.upenn.edu/~eir/papers/2014/coercible/coercible.pdf>`__.
 
.. _constraint-kind:
......@@ -10610,7 +10609,7 @@ for constructing pretty-printed error messages, ::
| ErrorMessage :<>: ErrorMessage -- Put two chunks of error message next to each other
| ErrorMessage :$$: ErrorMessage -- Put two chunks of error message above each other
 
in the ``GHC.TypeLits`` :base-ref:`module <GHC-TypeLits.html>`.
in the :base-ref:`GHC.TypeLits.` module.
 
For instance, we might use this interface to provide a more useful error
message for applications of ``show`` on unsaturated functions like this, ::
......@@ -10748,7 +10747,7 @@ Haskell <http://research.microsoft.com/~simonpj/papers/meta-haskell/>`__"
 
The `Template Haskell <http://www.haskell.org/haskellwiki/Template_Haskell>`__
page on the GHC Wiki has a wealth of information. You may also consult the
:th-ref:`Haddock reference documentation <Language-Haskell-TH.html>`.
:th-ref:`Haddock reference documentation <Language.Haskell.TH.>`.
Many changes to the original
design are described in `Notes on Template Haskell version
2 <http://research.microsoft.com/~simonpj/papers/meta-haskell/notes2.ps>`__.
......@@ -11495,7 +11494,7 @@ more details, see
 
With the :ghc-flag:`-XArrows` flag, GHC supports the arrow notation described in
the second of these papers, translating it using combinators from the
:base-ref:`Control.Arrow <Control-Arrow.html>` module.
:base-ref:`Control.Arrow.` module.
What follows is a brief introduction to the notation; it won't make much
sense unless you've read Hughes's paper.
 
......@@ -11595,8 +11594,8 @@ You can read this much like ordinary ``do``-notation, but with commands
in place of monadic expressions. The first line sends the value of
``x+1`` as an input to the arrow ``f``, and matches its output against
``y``. In the next line, the output is discarded. The arrow ``returnA``
is defined in the :base-ref:`Control.Arrow <Control-Arrow.html>` module as ``arr
id``. The above example is treated as an abbreviation for ::
is defined in the :base-ref:`Control.Arrow.` module as ``arr id``. The above
example is treated as an abbreviation for ::
 
arr (\ x -> (x, x)) >>>
first (arr (\ x -> x+1) >>> f) >>>
......@@ -11610,8 +11609,7 @@ id``. The above example is treated as an abbreviation for ::
 
Note that variables not used later in the composition are projected out.
After simplification using rewrite rules (see :ref:`rewrite-rules`)
defined in the :base-ref:`Control.Arrow <Control-Arrow.html>` module, this
reduces to ::
defined in the :base-ref:`Control.Arrow.` module, this reduces to ::
 
arr (\ x -> (x+1, x)) >>>
first f >>>
......@@ -11853,7 +11851,7 @@ to check arrow programs with GHC; tracing type errors in the
preprocessor output is not easy. Modules intended for both GHC and the
preprocessor must observe some additional restrictions:
 
- The module must import :base-ref:`Control.Arrow <Control-Arrow.html>`.
- The module must import :base-ref:`Control.Arrow.`.
 
- The preprocessor cannot cope with other Haskell extensions. These
would have to go in separate modules.
......@@ -12388,7 +12386,7 @@ will be rewritten to ``e``. You can also disable assertions using the
allows enabling assertions even when optimisation is turned on.
 
Assertion failures can be caught, see the documentation for the
:base-ref:`Control.Exception <Control-Exception.html>` library for the details.
:base-ref:`Control.Exception` library for the details.
 
.. _static-pointers:
 
......@@ -12425,12 +12423,11 @@ Using static pointers
---------------------
 
Each reference is given a key which can be used to locate it at runtime
with
:base-ref:`unsafeLookupStaticPtr <GHC-StaticPtr.html#v%3AunsafeLookupStaticPtr>`
with :base-ref:`GHC.StaticPtr.unsafeLookupStaticPtr`
which uses a global and immutable table called the Static Pointer Table.
The compiler includes entries in this table for all static forms found
in the linked modules. The value can be obtained from the reference via
:base-ref:`deRefStaticPtr <GHC-StaticPtr.html#v%3AdeRefStaticPtr>`.
:base-ref:`GHC.StaticPtr.deRefStaticPtr`.
 
The body ``e`` of a ``static e`` expression must be a closed expression. Where
we say an expression is *closed* when all of its free (type) variables are
......@@ -12491,7 +12488,7 @@ The only predefined instance is the obvious one that does nothing: ::
instance IsStatic StaticPtr where
fromStaticPtr sptr = sptr
 
See :base-ref:`IsStatic <GHC-StaticPtr.html#t%3AIsStatic>`.
See :base-ref:`GHC.StaticPtr.IsStatic`.
 
Furthermore, type ``t`` is constrained to have a ``Typeable`` instance.
The following are therefore illegal: ::
......@@ -12587,9 +12584,8 @@ A list of all supported language extensions can be obtained by invoking
``ghc --supported-extensions`` (see :ghc-flag:`--supported-extensions`).
 
Any extension from the ``Extension`` type defined in
:cabal-ref:`Language.Haskell.Extension <Language-Haskell-Extension.html>`
may be used. GHC will report an error if any of the requested extensions
are not supported.
:cabal-ref:`Language.Haskell.Extension.` may be used. GHC will report an error
if any of the requested extensions are not supported.
 
.. _options-pragma:
 
......@@ -13870,14 +13866,12 @@ Special built-in functions
 
GHC has a few built-in functions with special behaviour. In particular:
 
- :base-ref:`inline <GHC-Exts.html#v%3Ainline>`
allows control over inlining on a per-call-site basis.
- :base-ref:`GHC.Exts.inline` allows control over inlining on a per-call-site basis.
 
- :base-ref:`lazy <GHC-Exts.html#v%3Alazy>` restrains the strictness analyser.
- :base-ref:`GHC.Exts.lazy` restrains the strictness analyser.
 
- :base-ref:`oneShot <GHC-Exts.html#v%3AoneShot>`
gives a hint to the compiler about how often a function is being
called.
- :base-ref:`GHC.Exts.oneShot` gives a hint to the compiler about how often a
function is being called.
 
.. _generic-classes:
 
......@@ -13896,11 +13890,9 @@ Generic programming
===================
 
Using a combination of :ghc-flag:`-XDeriveGeneric`,
:ghc-flag:`-XDefaultSignatures`, and
:ghc-flag:`-XDeriveAnyClass`, you can easily do
datatype-generic programming using the :base-ref:`GHC.Generics
<GHC-Generics.html>` framework. This section gives a very brief overview of how
to do it.
:ghc-flag:`-XDefaultSignatures`, and :ghc-flag:`-XDeriveAnyClass`, you can
easily do datatype-generic programming using the :base-ref:`GHC.Generics.`
framework. This section gives a very brief overview of how to do it.
 
Generic programming support in GHC allows defining classes with methods
that do not need a user specification when instantiating: the method
......
......@@ -24,8 +24,7 @@ package. All you need to do is write a simple configuration file, put a
few files in the right places, and you have a package. See the `Cabal
documentation <http://www.haskell.org/cabal/users-guide/>`__ for
details, and also the Cabal libraries
(:cabal-ref:`Distribution.Simple <Distribution-Simple.html>`,
for example).
(:cabal-ref:`Distribution.Simple.`, for example).
.. _using-packages:
......@@ -1033,8 +1032,7 @@ package as well.
-------------------------------------------------
A package specification is a Haskell record; in particular, it is the
record
:cabal-ref:`InstalledPackageInfo <Distribution-InstalledPackageInfo.html#%tInstalledPackageInfo>`
record :cabal-ref:`Distribution.InstalledPackageInfo.InstalledPackageInfo`
in the module Distribution.InstalledPackageInfo, which is part of the
Cabal package distributed with GHC.
......@@ -1142,7 +1140,7 @@ The allowed fields, with their types, are:
(string) The type of license under which this package is
distributed. This field is a value of the
:cabal-ref:`License <Distribution-License.html#t:License>` type.
:cabal-ref:`Distribution.License.License` type.
``license-file``
.. index::
......
......@@ -37,8 +37,7 @@ squad <http://research.microsoft.com/%7Esimonpj/papers/marktoberdorf/>`__.
To the programmer, Concurrent Haskell introduces no new language
constructs; rather, it appears simply as a library,
:base-ref:`Control.Concurrent <Control-Concurrent.html>`.
The functions exported by this library include:
:base-ref:`Control.Concurrent.`. The functions exported by this library include:
- Forking and killing threads.
......
......@@ -349,9 +349,9 @@ for all modules in a program.
Adds an automatic ``SCC`` annotation to all *call sites*. This is
particularly useful when using profiling for the purposes of
generating stack traces; see the function :base-ref:`traceStack <Debug-Trace.html#traceShow>` in the
module ``Debug.Trace``, or the :rts-flag:`-xc` RTS flag
(:ref:`rts-options-debugging`) for more details.
generating stack traces; see the function :base-ref:`Debug.Trace.traceShow`,
or the :rts-flag:`-xc` RTS flag (:ref:`rts-options-debugging`) for more
details.
.. ghc-flag:: -fprof-cafs
......
......@@ -247,7 +247,7 @@ Miscellaneous RTS options
:default: 100k
This option relates to allocation limits; for more about this see
:base-ref:`enableAllocationLimit <GHC-Conc.html#v%3AenableAllocationLimit>`.
:base-ref:`GHC.Conc.enableAllocationLimit`.
When a thread hits its allocation limit, the RTS throws an exception
to the thread, and the thread gets an additional quota of allocation
before the exception is raised again, the idea being so that the
......@@ -439,7 +439,7 @@ performance.
parallel GC completely, reverting to sequential GC.
The default parallel GC settings are usually suitable for parallel programs
(i.e. those using :base-ref:`par <GHC-Conc.html#v:par>`, Strategies, or with
(i.e. those using :base-ref:`GHC.Conc.par`, Strategies, or with
multiple threads). However, it is sometimes beneficial to enable the
parallel GC for a single-threaded sequential program too, especially if the
program has a large amount of heap data and GC is a significant fraction of
......@@ -732,7 +732,7 @@ RTS options to produce runtime statistics
output is sent to ``stderr``.
If you use the ``-T`` flag then, you should access the statistics
using :base-ref:`GHC.Stats <GHC-Stats.html>`.
using :base-ref:`GHC.Stats.`.
If you use the ``-t`` flag then, when your program finishes, you
will see something like this:
......
......@@ -298,9 +298,9 @@ Don't use ``Float``\s:
Use unboxed arrays (``UArray``)
GHC supports arrays of unboxed elements, for several basic
arithmetic element types including ``Int`` and ``Char``: see the
``Data.Array.Unboxed`` library for details. These arrays are likely
to be much faster than using standard Haskell 98 arrays from the
``Data.Array`` library.
:array-ref:`Data.Array.Unboxed.` library for details. These arrays are
likely to be much faster than using standard Haskell 98 arrays from the
:array-ref:`Data.Array.` library.
Use a bigger heap!
If your program's GC stats (:rts-flag:`-S [⟨file⟩]` RTS option) indicate
......@@ -312,7 +312,7 @@ Use a bigger heap!
to let GHC calculate a value based on the amount of live data.
Compact your data:
The :ghc-compact-ref:`GHC.Compact <GHC-Compact.html>` module
The :ghc-compact-ref:`GHC.Compact.` module
provides a way to make garbage collection more efficient for
long-lived data structures. Compacting a data structure collects
the objects together in memory, where they are treated as a single
......@@ -334,7 +334,7 @@ Warning: except in certain specialised cases (like Happy parsers) this is likely
to actually *increase* the size of your program, because unfolding generally
enables extra simplifying optimisations to be performed.
Avoid ``Read``.
Avoid :base-ref:`Prelude.Read`.
Use :command:`strip` on your executables.
......
......@@ -9,9 +9,8 @@ Using Concurrent Haskell
GHC supports Concurrent Haskell by default, without requiring a special
option or libraries compiled in a certain way. To get access to the
support libraries for Concurrent Haskell, just import
:base-ref:`Control.Concurrent <Control-Concurrent.html>`.
More information on Concurrent Haskell is provided in the documentation
for that module.
:base-ref:`Control.Concurrent.`. More information on Concurrent Haskell is
provided in the documentation for that module.
Optionally, the program may be linked with the :ghc-flag:`-threaded` option (see
:ref:`options-linker`. This provides two benefits:
......@@ -104,8 +103,7 @@ RTS options for SMP parallelism
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
There are two ways to run a program on multiple processors: call
:base-ref:`Control.Concurrent.setNumCapabilities
<Control.Concurrent.html#v:setNumCapabilities>` from your program, or
:base-ref:`Control.Concurrent.setNumCapabilities` from your program, or
use the RTS :rts-flag:`-N ⟨x⟩` options.
.. rts-flag:: -N ⟨x⟩
......@@ -174,7 +172,7 @@ CPUs:
This option is probably only of use for concurrent programs that
explicitly schedule threads onto CPUs with
:base-ref:`Control.Concurrent.forkOn <Control-Concurrent.html#v:forkOn>`.
:base-ref:`Control.Concurrent.forkOn`.
Hints for using SMP parallelism
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
......
......@@ -53,8 +53,7 @@ afterwards has no effect on the shell.
This problem doesn't just affect GHCi, it affects any GHC-compiled
program that wants to catch console events. See the
:base-ref:`GHC.ConsoleHandler <GHC-ConsoleHandler.html>`
module.
:base-ref:`GHC.ConsoleHandler.` module.
.. _terminal-interaction:
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment